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