001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.debug.core;
011:
012: import java.util.List;
013:
014: import org.eclipse.debug.core.DebugException;
015: import org.eclipse.debug.core.model.IDropToFrame;
016: import org.eclipse.debug.core.model.IFilteredStep;
017: import org.eclipse.debug.core.model.IStackFrame;
018:
019: /**
020: * A stack frame in a thread on a Java virtual machine.
021: * <p>
022: * Clients are not intended to implement this interface.
023: * </p>
024: * <p>
025: * Since 3.1, <code>IJavaStackFrame</code> also implements
026: * {@link org.eclipse.debug.core.model.IDropToFrame}.
027: * </p>
028: * @see org.eclipse.debug.core.model.IStackFrame
029: */
030:
031: public interface IJavaStackFrame extends IStackFrame, IJavaModifiers,
032: IFilteredStep, IDropToFrame {
033:
034: /**
035: * Status code indicating a stack frame is invalid. A stack frame becomes invalid
036: * when the thread containing the stack frame resumes. A stack frame may or may
037: * not be valid if the thread subsequently suspends, depending on the location
038: * where the thread suspends.
039: *
040: * @since 3.1
041: */
042: public static final int ERR_INVALID_STACK_FRAME = 130;
043:
044: /**
045: * Returns whether this stack frame currently supports the drop
046: * to frame operation. Note that not all VMs support the operation.
047: *
048: * @return whether this stack frame currently supports drop to frame
049: * @deprecated since 3.1, IJavaStackFrame extends org.eclipse.debug.core.IDropToFrame
050: * which defines canDropToFrame(). Use this method instead.
051: */
052: boolean supportsDropToFrame();
053:
054: /**
055: * Returns whether the method associated with this stack frame
056: * is a constructor.
057: *
058: * @return whether this stack frame is associated with a constructor
059: * @exception DebugException if this method fails. Reasons include:
060: * <ul>
061: * <li>Failure communicating with the VM. The DebugException's
062: * status code contains the underlying exception responsible for
063: * the failure.</li>
064: * <li>This stack frame is no longer valid. That is, the thread
065: * containing this stack frame has since been resumed.</li>
066: * </ul>
067: */
068: public boolean isConstructor() throws DebugException;
069:
070: /**
071: * Returns whether the method associated with this stack frame
072: * has been declared as native.
073: *
074: * @return whether this stack frame has been declared as native
075: * @exception DebugException if this method fails. Reasons include:
076: * <ul>
077: * <li>Failure communicating with the VM. The DebugException's
078: * status code contains the underlying exception responsible for
079: * the failure.</li>
080: * <li>This stack frame is no longer valid. That is, the thread
081: * containing this stack frame has since been resumed.</li>
082: * </ul>
083: */
084: public boolean isNative() throws DebugException;
085:
086: /**
087: * Returns whether the method associated with this stack frame
088: * is a static initializer.
089: *
090: * @return whether this stack frame is a static initializer
091: * @exception DebugException if this method fails. Reasons include:<ul>
092: * <ul>
093: * <li>Failure communicating with the VM. The DebugException's
094: * status code contains the underlying exception responsible for
095: * the failure.</li>
096: * <li>This stack frame is no longer valid. That is, the thread
097: * containing this stack frame has since been resumed.</li>
098: * </ul>
099: */
100: public boolean isStaticInitializer() throws DebugException;
101:
102: /**
103: * Returns whether the method associated with this stack frame
104: * has been declared as synchronized.
105: *
106: * @return whether this stack frame has been declared as synchronized
107: * @exception DebugException if this method fails. Reasons include:
108: * <ul>
109: * <li>Failure communicating with the VM. The DebugException's
110: * status code contains the underlying exception responsible for
111: * the failure.</li>
112: * <li>This stack frame is no longer valid. That is, the thread
113: * containing this stack frame has since been resumed.</li>
114: * </ul>
115: */
116: public boolean isSynchronized() throws DebugException;
117:
118: /**
119: * Returns whether the method associated with this stack frame
120: * is running code in the VM that is out of synch with the code
121: * in the workspace.
122: *
123: * @return whether this stack frame is out of synch with the workspace.
124: * @exception DebugException if this method fails. Reasons include:
125: * <ul>
126: * <li>Failure communicating with the VM. The DebugException's
127: * status code contains the underlying exception responsible for
128: * the failure.</li>
129: * <li>This stack frame is no longer valid. That is, the thread
130: * containing this stack frame has since been resumed.</li>
131: * </ul>
132: * @since 2.0
133: */
134: public boolean isOutOfSynch() throws DebugException;
135:
136: /**
137: * Returns whether the method associated with this stack frame is
138: * obsolete, that is, it is running old byte codes that have been
139: * replaced in the VM. This can occur when a hot code replace
140: * succeeds but the VM is unable to pop a call to an affected
141: * method from the call stack.
142: * @return whether this stack frame's method is obsolete
143: * @exception DebugException if this method fails. Reasons include:
144: * <ul>
145: * <li>Failure communicating with the VM. The DebugException's
146: * status code contains the underlying exception responsible for
147: * the failure.</li>
148: * <li>This stack frame is no longer valid. That is, the thread
149: * containing this stack frame has since been resumed.</li>
150: * </ul>
151: * @since 2.0
152: */
153: public boolean isObsolete() throws DebugException;
154:
155: /**
156: * Returns the fully qualified name of the type that declares the method
157: * associated with this stack frame.
158: *
159: * @return declaring type name
160: * @exception DebugException if this method fails. Reasons include:
161: * <ul>
162: * <li>Failure communicating with the VM. The DebugException's
163: * status code contains the underlying exception responsible for
164: * the failure.</li>
165: * <li>This stack frame is no longer valid. That is, the thread
166: * containing this stack frame has since been resumed.</li>
167: * </ul>
168: */
169: public String getDeclaringTypeName() throws DebugException;
170:
171: /**
172: * Returns the fully qualified name of the type that is the receiving object
173: * associated with this stack frame
174: *
175: * @return receiving type name
176: * @exception DebugException if this method fails. Reasons include:
177: * <ul>
178: * <li>Failure communicating with the VM. The DebugException's
179: * status code contains the underlying exception responsible for
180: * the failure.</li>
181: * <li>This stack frame is no longer valid. That is, the thread
182: * containing this stack frame has since been resumed.</li>
183: * </ul>
184: */
185: public String getReceivingTypeName() throws DebugException;
186:
187: /**
188: * Returns the JNI signature for the method this stack frame is associated with.
189: *
190: * @return signature
191: * @exception DebugException if this method fails. Reasons include:
192: * <ul>
193: * <li>Failure communicating with the VM. The DebugException's
194: * status code contains the underlying exception responsible for
195: * the failure.</li>
196: * <li>This stack frame is no longer valid. That is, the thread
197: * containing this stack frame has since been resumed.</li>
198: * </ul>
199: */
200: public String getSignature() throws DebugException;
201:
202: /**
203: * Returns a list of fully qualified type names of the arguments for the method
204: * associated with this stack frame.
205: *
206: * @return argument type names, or an empty list if this method has no arguments
207: * @exception DebugException if this method fails. Reasons include:
208: * <ul>
209: * <li>Failure communicating with the VM. The DebugException's
210: * status code contains the underlying exception responsible for
211: * the failure.</li>
212: * <li>This stack frame is no longer valid. That is, the thread
213: * containing this stack frame has since been resumed.</li>
214: * </ul>
215: */
216: public List getArgumentTypeNames() throws DebugException;
217:
218: /**
219: * Returns the name of the method associated with this stack frame
220: *
221: * @return method name
222: * @exception DebugException if this method fails. Reasons include:
223: * <ul>
224: * <li>Failure communicating with the VM. The DebugException's
225: * status code contains the underlying exception responsible for
226: * the failure.</li>
227: * <li>This stack frame is no longer valid. That is, the thread
228: * containing this stack frame has since been resumed.</li>
229: * </ul>
230: */
231: public String getMethodName() throws DebugException;
232:
233: /**
234: * Returns the local, static, or "this" variable with the given
235: * name, or <code>null</code> if unable to resolve a variable with the name.
236: *
237: * @param variableName the name of the variable to search for
238: * @return a variable, or <code>null</code> if none
239: * @exception DebugException if this method fails. Reasons include:
240: * <ul>
241: * <li>Failure communicating with the VM. The DebugException's
242: * status code contains the underlying exception responsible for
243: * the failure.</li>
244: * <li>This stack frame is no longer valid. That is, the thread
245: * containing this stack frame has since been resumed.</li>
246: * </ul>
247: */
248: public IJavaVariable findVariable(String variableName)
249: throws DebugException;
250:
251: /**
252: * Returns the line number of the instruction pointer in
253: * this stack frame that corresponds to the line in the associated source
254: * element in the specified stratum, or <code>-1</code> if line number
255: * information is unavailable.
256: *
257: * @param stratum the stratum to use.
258: * @return line number of instruction pointer in this stack frame, or
259: * <code>-1</code> if line number information is unavailable
260: * @exception DebugException if this method fails. Reasons include:
261: * <ul><li>Failure communicating with the debug target. The DebugException's
262: * status code contains the underlying exception responsible for
263: * the failure.</li>
264: * </ul>
265: *
266: * @since 3.0
267: */
268: public int getLineNumber(String stratum) throws DebugException;
269:
270: /**
271: * Returns the source name debug attribute associated with the declaring
272: * type of this stack frame, or <code>null</code> if the source name debug
273: * attribute not present.
274: *
275: * @return source name debug attribute, or <code>null</code>
276: * @exception DebugException if this method fails. Reasons include:
277: * <ul>
278: * <li>Failure communicating with the VM. The DebugException's
279: * status code contains the underlying exception responsible for
280: * the failure.</li>
281: * <li>This stack frame is no longer valid. That is, the thread
282: * containing this stack frame has since been resumed.</li>
283: * </ul>
284: */
285: public String getSourceName() throws DebugException;
286:
287: /**
288: * Returns the source name debug attribute associated with the declaring
289: * type of this stack frame in the specified stratum, or <code>null</code>
290: * if the source name debug attribute not present.
291: *
292: * @param stratum the stratum to use.
293: * @return source name debug attribute, or <code>null</code>
294: * @exception DebugException if this method fails. Reasons include:
295: * <ul>
296: * <li>Failure communicating with the VM. The DebugException's
297: * status code contains the underlying exception responsible for
298: * the failure.</li>
299: * <li>This stack frame is no longer valid. That is, the thread
300: * containing this stack frame has since been resumed.</li>
301: * </ul>
302: *
303: * @since 3.0
304: */
305: public String getSourceName(String stratum) throws DebugException;
306:
307: /**
308: * Returns the source path debug attribute associated with
309: * this stack frame in the specified stratum, or
310: * <code>null</code> if the source path is not known.
311: *
312: * @param stratum the stratum to use.
313: * @return source path debug attribute, or <code>null</code>
314: * @exception DebugException if this method fails. Reasons include:
315: * <ul>
316: * <li>Failure communicating with the VM. The DebugException's
317: * status code contains the underlying exception responsible for
318: * the failure.</li>
319: * <li>This stack frame is no longer valid. That is, the thread
320: * containing this stack frame has since been resumed.</li>
321: * </ul>
322: * @since 3.0
323: */
324: public String getSourcePath(String stratum) throws DebugException;
325:
326: /**
327: * Returns the source path debug attribute associated with
328: * this stack frame, or <code>null</code> if the source path
329: * is not known.
330: *
331: * @return source path debug attribute, or <code>null</code>
332: * @exception DebugException if this method fails. Reasons include:
333: * <ul>
334: * <li>Failure communicating with the VM. The DebugException's
335: * status code contains the underlying exception responsible for
336: * the failure.</li>
337: * <li>This stack frame is no longer valid. That is, the thread
338: * containing this stack frame has since been resumed.</li>
339: * </ul>
340: * @since 3.0
341: */
342: public String getSourcePath() throws DebugException;
343:
344: /**
345: * Returns a collection of local variables that are visible
346: * at the current point of execution in this stack frame. The
347: * list includes arguments.
348: *
349: * @return collection of locals and arguments
350: * @exception DebugException if this method fails. Reasons include:
351: * <ul>
352: * <li>Failure communicating with the VM. The DebugException's
353: * status code contains the underlying exception responsible for
354: * the failure.</li>
355: * <li>This stack frame is no longer valid. That is, the thread
356: * containing this stack frame has since been resumed.</li>
357: * </ul>
358: * @since 2.0
359: */
360: public IJavaVariable[] getLocalVariables() throws DebugException;
361:
362: /**
363: * Returns a reference to the receiver of the method associated
364: * with this stack frame, or <code>null</code> if this stack frame
365: * represents a static method.
366: *
367: * @return 'this' object, or <code>null</code>
368: * @exception DebugException if this method fails. Reasons include:
369: * <ul>
370: * <li>Failure communicating with the VM. The DebugException's
371: * status code contains the underlying exception responsible for
372: * the failure.</li>
373: * <li>This stack frame is no longer valid. That is, the thread
374: * containing this stack frame has since been resumed.</li>
375: * </ul>
376: */
377: public IJavaObject getThis() throws DebugException;
378:
379: /**
380: * Returns the class in which this stack frame's method is
381: * declared.
382: *
383: * @return the class in which this stack frame's method is
384: * declared
385: * @exception DebugException if this method fails. Reasons include:
386: * <ul>
387: * <li>Failure communicating with the VM. The DebugException's
388: * status code contains the underlying exception responsible for
389: * the failure.</li>
390: * <li>This stack frame is no longer valid. That is, the thread
391: * containing this stack frame has since been resumed.</li>
392: * </ul>
393: * @since 2.0
394: * @deprecated Use <code>getReferenceType()</code> instead, as a method is not
395: * restricted to occur in a class. An interface may contain a synthetic
396: * class initializer methods. Since 3.1, this method throws a
397: * <code>DebugException</code> when a stack frame's method is contained
398: * in an interface.
399: */
400: public IJavaClassType getDeclaringType() throws DebugException;
401:
402: /**
403: * Returns the type in which this stack frame's method is
404: * declared.
405: *
406: * @return the type in which this stack frame's method is
407: * declared
408: * @exception DebugException if this method fails. Reasons include:
409: * <ul>
410: * <li>Failure communicating with the VM. The DebugException's
411: * status code contains the underlying exception responsible for
412: * the failure.</li>
413: * <li>This stack frame is no longer valid. That is, the thread
414: * containing this stack frame has since been resumed.</li>
415: * </ul>
416: * @since 3.1
417: */
418: public IJavaReferenceType getReferenceType() throws DebugException;
419:
420: /**
421: * Returns whether local variable information was available
422: * when local variables were retrieved from the target for this
423: * frame. Returns <code>true</code> if locals have never been
424: * retrieved. This data is available after the fact, since variable
425: * retrieval is expensive.
426: *
427: * @return whether local variable information was available
428: * when variables were retrieved from the target. Returns
429: * <code>true</code> if locals have never been retrieved
430: *
431: * @since 2.0
432: */
433: public boolean wereLocalsAvailable();
434:
435: /**
436: * Returns whether the method associated with this stack frame accepts
437: * a variable number of arguments.
438: *
439: * @return <code>true</code> if the method associated with this stack
440: * frame accepts a variable number of arguments, <code>false</code> otherwise.
441: * @exception DebugException if this method fails. Reasons include:
442: * <ul>
443: * <li>Failure communicating with the VM. The DebugException's
444: * status code contains the underlying exception responsible for
445: * the failure.</li>
446: * <li>This stack frame is no longer valid. That is, the thread
447: * containing this stack frame has since been resumed.</li>
448: * </ul>
449: * @since 3.1
450: */
451: public boolean isVarArgs() throws DebugException;
452:
453: /**
454: * Returns whether this frame currently supports a force return operation. That is,
455: * can this method force a return before it reaches a return statement. Not all VMs
456: * support this feature.
457: * <p>
458: * Force return is only available when a thread is suspended.
459: * </p>
460: * @return whether force return can be performed currently
461: * @since 3.3
462: */
463: public boolean canForceReturn();
464:
465: /**
466: * Steps out of this frame's method returning the given value. No further instructions
467: * in the method are executed but locks acquired by entering synchronized blocks are released.
468: * The following conditions must be satisfied:
469: * <ul>
470: * <li>This frame must be suspended in a non-native method.</li>
471: * <li>The return value must be assignment compatible with this frame's method's
472: * return type. Use a void value when a method return type is void
473: * (see <code>IJavaDebugTarget.voidValue()</code>).</li>
474: * </ul>
475: *
476: * @param value return value that must be assignment compatible with this frame's
477: * method's return value
478: * @throws DebugException if the operation fails
479: * @since 3.3
480: */
481: public void forceReturn(IJavaValue value) throws DebugException;
482: }
|