/*******************************************************************************
* Copyright (c) 2000, 2011 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.jdt.debug.core;
import java.util.List;
import org.eclipse.debug.core.DebugException;
import org.eclipse.debug.core.model.IDropToFrame;
import org.eclipse.debug.core.model.IFilteredStep;
import org.eclipse.debug.core.model.IStackFrame;
/**
* A stack frame in a thread on a Java virtual machine.
* <p>
* Since 3.1, <code>IJavaStackFrame</code> also implements
* {@link org.eclipse.debug.core.model.IDropToFrame}.
* </p>
*
* @see org.eclipse.debug.core.model.IStackFrame
* @noimplement This interface is not intended to be implemented by clients.
* @noextend This interface is not intended to be extended by clients.
*/
@SuppressWarnings("deprecation")
public interface IJavaStackFrame extends IStackFrame, IJavaModifiers,
IFilteredStep, IDropToFrame {
/**
* Status code indicating a stack frame is invalid. A stack frame becomes
* invalid when the thread containing the stack frame resumes. A stack frame
* may or may not be valid if the thread subsequently suspends, depending on
* the location where the thread suspends.
*
* @since 3.1
*/
public static final int ERR_INVALID_STACK_FRAME = 130;
/**
* Returns whether this stack frame currently supports the drop to frame
* operation. Note that not all VMs support the operation.
*
* @return whether this stack frame currently supports drop to frame
* @deprecated since 3.1, IJavaStackFrame extends
* org.eclipse.debug.core.IDropToFrame which defines
* canDropToFrame(). Use this method instead.
*/
@Deprecated
boolean supportsDropToFrame();
/**
* Returns whether the method associated with this stack frame is a
* constructor.
*
* @return whether this stack frame is associated with a constructor
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public boolean isConstructor() throws DebugException;
/**
* Returns whether the method associated with this stack frame has been
* declared as native.
*
* @return whether this stack frame has been declared as native
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public boolean isNative() throws DebugException;
/**
* Returns whether the method associated with this stack frame is a static
* initializer.
*
* @return whether this stack frame is a static initializer
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public boolean isStaticInitializer() throws DebugException;
/**
* Returns whether the method associated with this stack frame has been
* declared as synchronized.
*
* @return whether this stack frame has been declared as synchronized
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public boolean isSynchronized() throws DebugException;
/**
* Returns whether the method associated with this stack frame is running
* code in the VM that is out of synch with the code in the workspace.
*
* @return whether this stack frame is out of synch with the workspace.
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 2.0
*/
public boolean isOutOfSynch() throws DebugException;
/**
* Returns whether the method associated with this stack frame is obsolete,
* that is, it is running old byte codes that have been replaced in the VM.
* This can occur when a hot code replace succeeds but the VM is unable to
* pop a call to an affected method from the call stack.
*
* @return whether this stack frame's method is obsolete
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 2.0
*/
public boolean isObsolete() throws DebugException;
/**
* Returns the fully qualified name of the type that declares the method
* associated with this stack frame.
*
* @return declaring type name
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public String getDeclaringTypeName() throws DebugException;
/**
* Returns the fully qualified name of the type that is the receiving object
* associated with this stack frame
*
* @return receiving type name
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public String getReceivingTypeName() throws DebugException;
/**
* Returns the JNI signature for the method this stack frame is associated
* with.
*
* @return signature
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public String getSignature() throws DebugException;
/**
* Returns a list of fully qualified type names of the arguments for the
* method associated with this stack frame.
*
* @return argument type names, or an empty list if this method has no
* arguments
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public List<String> getArgumentTypeNames() throws DebugException;
/**
* Returns the name of the method associated with this stack frame
*
* @return method name
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public String getMethodName() throws DebugException;
/**
* Returns the local, static, or "this" variable with the given name, or
* <code>null</code> if unable to resolve a variable with the name.
*
* @param variableName
* the name of the variable to search for
* @return a variable, or <code>null</code> if none
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public IJavaVariable findVariable(String variableName)
throws DebugException;
/**
* Returns the line number of the instruction pointer in this stack frame
* that corresponds to the line in the associated source element in the
* specified stratum, or <code>-1</code> if line number information is
* unavailable.
*
* @param stratum
* the stratum to use.
* @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>
*
* @since 3.0
*/
public int getLineNumber(String stratum) throws DebugException;
/**
* Returns the source name debug attribute associated with the declaring
* type of this stack frame, or <code>null</code> if the source name debug
* attribute not present.
*
* @return source name debug attribute, or <code>null</code>
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public String getSourceName() throws DebugException;
/**
* Returns the source name debug attribute associated with the declaring
* type of this stack frame in the specified stratum, or <code>null</code>
* if the source name debug attribute not present.
*
* @param stratum
* the stratum to use.
* @return source name debug attribute, or <code>null</code>
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*
* @since 3.0
*/
public String getSourceName(String stratum) throws DebugException;
/**
* Returns the source path debug attribute associated with this stack frame
* in the specified stratum, or <code>null</code> if the source path is not
* known.
*
* @param stratum
* the stratum to use.
* @return source path debug attribute, or <code>null</code>
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 3.0
*/
public String getSourcePath(String stratum) throws DebugException;
/**
* Returns the source path debug attribute associated with this stack frame,
* or <code>null</code> if the source path is not known.
*
* @return source path debug attribute, or <code>null</code>
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 3.0
*/
public String getSourcePath() throws DebugException;
/**
* Returns a collection of local variables that are visible at the current
* point of execution in this stack frame. The list includes arguments.
*
* @return collection of locals and arguments
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 2.0
*/
public IJavaVariable[] getLocalVariables() throws DebugException;
/**
* Returns a reference to the receiver of the method associated with this
* stack frame, or <code>null</code> if this stack frame represents a static
* method.
*
* @return 'this' object, or <code>null</code>
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
*/
public IJavaObject getThis() throws DebugException;
/**
* Returns the class in which this stack frame's method is declared.
*
* @return the class in which this stack frame's method is declared
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 2.0
* @deprecated Use <code>getReferenceType()</code> instead, as a method is
* not restricted to occur in a class. An interface may contain
* a synthetic class initializer methods. Since 3.1, this method
* throws a <code>DebugException</code> when a stack frame's
* method is contained in an interface.
*/
@Deprecated
public IJavaClassType getDeclaringType() throws DebugException;
/**
* Returns the type in which this stack frame's method is declared.
*
* @return the type in which this stack frame's method is declared
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 3.1
*/
public IJavaReferenceType getReferenceType() throws DebugException;
/**
* Returns whether local variable information was available when local
* variables were retrieved from the target for this frame. Returns
* <code>true</code> if locals have never been retrieved. This data is
* available after the fact, since variable retrieval is expensive.
*
* @return whether local variable information was available when variables
* were retrieved from the target. Returns <code>true</code> if
* locals have never been retrieved
*
* @since 2.0
*/
public boolean wereLocalsAvailable();
/**
* Returns whether the method associated with this stack frame accepts a
* variable number of arguments.
*
* @return <code>true</code> if the method associated with this stack frame
* accepts a variable number of arguments, <code>false</code>
* otherwise.
* @exception DebugException
* if this method fails. Reasons include:
* <ul>
* <li>Failure communicating with the VM. The
* DebugException's status code contains the underlying
* exception responsible for the failure.</li>
* <li>This stack frame is no longer valid. That is, the
* thread containing this stack frame has since been resumed.
* </li>
* </ul>
* @since 3.1
*/
public boolean isVarArgs() throws DebugException;
/**
* Returns whether this frame currently supports a force return operation.
* That is, can this method force a return before it reaches a return
* statement. Not all VMs support this feature.
* <p>
* Force return is only available when a thread is suspended.
* </p>
*
* @return whether force return can be performed currently
* @since 3.3
*/
public boolean canForceReturn();
/**
* Steps out of this frame's method returning the given value. No further
* instructions in the method are executed but locks acquired by entering
* synchronized blocks are released. The following conditions must be
* satisfied:
* <ul>
* <li>This frame must be suspended in a non-native method.</li>
* <li>The return value must be assignment compatible with this frame's
* method's return type. Use a void value when a method return type is void
* (see <code>IJavaDebugTarget.voidValue()</code>).</li>
* </ul>
*
* @param value
* return value that must be assignment compatible with this
* frame's method's return value
* @throws DebugException
* if the operation fails
* @since 3.3
*/
public void forceReturn(IJavaValue value) throws DebugException;
}