/*******************************************************************************
* 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 org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.debug.core.DebugException;
import org.eclipse.debug.core.model.IFilteredStep;
import org.eclipse.debug.core.model.IThread;
/**
* A thread in a Java virtual machine.
*
* @see org.eclipse.debug.core.model.IThread
* @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 IJavaThread extends IThread, IFilteredStep {
/**
* Status code indicating a request failed because a thread was not
* suspended.
*/
public static final int ERR_THREAD_NOT_SUSPENDED = 100;
/**
* Status code indicating a request to perform a message send failed because
* a thread was already performing a message send.
*
* @see IJavaObject#sendMessage(String, String, IJavaValue[], IJavaThread,
* boolean)
* @see IJavaClassType#sendMessage(String, String, IJavaValue[],
* IJavaThread)
* @see IJavaClassType#newInstance(String, IJavaValue[], IJavaThread)
*/
public static final int ERR_NESTED_METHOD_INVOCATION = 101;
/**
* Status code indicating a request to perform a message send failed because
* a thread was not suspended by a step or breakpoint event. When a thread
* is suspended explicitly via the <code>suspend()</code> method, it is not
* able to perform method invocations (this is a JDI limitation).
*
* @see IJavaObject#sendMessage(String, String, IJavaValue[], IJavaThread,
* boolean)
* @see IJavaClassType#sendMessage(String, String, IJavaValue[],
* IJavaThread)
* @see IJavaClassType#newInstance(String, IJavaValue[], IJavaThread)
*/
public static final int ERR_INCOMPATIBLE_THREAD_STATE = 102;
/**
* Returns whether this thread is a system thread.
*
* @return whether this thread is a system thread
* @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>
* </ul>
*/
boolean isSystemThread() throws DebugException;
/**
* Returns whether any of the stack frames associated with this thread are
* running code in the VM that is out of synch with the code in the
* workspace.
*
* @return whether this thread 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>
* @since 2.0
*/
boolean isOutOfSynch() throws DebugException;
/**
* Returns whether this thread may be running code in the VM that is out of
* synch with the code in the workspace.
*
* @return whether this thread may be 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>
* @since 2.0
*/
boolean mayBeOutOfSynch() throws DebugException;
/**
* Returns whether this thread is currently performing an evaluation.
*
* @return whether this thread is currently performing an evaluation
* @since 2.0
*/
boolean isPerformingEvaluation();
/**
* Returns the name of the thread group this thread belongs to, or
* <code>null</code> if none.
*
* @return thread group name, 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>
* </ul>
*/
String getThreadGroupName() throws DebugException;
/**
* Returns a variable with the given name, or <code>null</code> if unable to
* resolve a variable with the name, or if this thread is not currently
* suspended.
* <p>
* Variable lookup works only when a thread is suspended. Lookup is
* performed in all stack frames, in a top-down order, returning the first
* successful match, or <code>null</code> if no match is found.
* </p>
*
* @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>
* </ul>
*/
IJavaVariable findVariable(String variableName) throws DebugException;
/**
* Invokes the given evaluation with the specified progress monitor. This
* thread fires a resume event when the evaluation begins, and a suspend
* event when the evaluation completes or throws an exception. The events
* are given a detail as specified by <code>evaluationDetail</code> (one of
* <code>DebugEvent.EVALUATION</code> or
* <code>DebugEvent.EVALUATION_IMPLICIT</code>).
* <p>
* Since 3.5, the <code>org.eclipse.jdt.debug.breakpointListeners</code>
* extension point supports evaluation execution during a listener call
* back. Suspend and resume events are not fired during listener call backs.
* Unspecified model specific events are fired.
* </p>
*
* @param evaluation
* the evaluation to perform
* @param monitor
* progress monitor (may be <code>null</code>
* @param evaluationDetail
* one of <code>DebugEvent.EVALUATION</code> or
* <code>DebugEvent.EVALUATION_IMPLICIT</code>
* @param hitBreakpoints
* whether or not breakpoints should be honored in this thread
* during the evaluation. If <code>false</code>, breakpoints hit
* in this thread during the evaluation will be ignored.
* @exception DebugException
* if an exception occurs performing the evaluation
* @since 2.0
*/
public void runEvaluation(IEvaluationRunnable evaluation,
IProgressMonitor monitor, int evaluationDetail,
boolean hitBreakpoints) throws DebugException;
/**
* Queues the given runnable with the list of runnables associated with this
* thread. Runnables are executed asynchronously in a separate thread. This
* method should be used to execute any code which performs an operation
* like a method invocation.
*
* @param runnable
* the runnable to execute.
* @since 2.1
*/
public void queueRunnable(Runnable runnable);
/**
* Attempts to terminate the currently executing
* <code>IEvaluationRunnable</code> in this thread, if any.
*
* Evaluations may be composed of a series of instructions. Terminating an
* evaluation means stopping the evaluation after the current instruction
* completes. A single instruction (such as a method invocation) cannot be
* interrupted.
*
* @exception DebugException
* if an exception occurs while terminating the evaluation.
* @since 2.1
*/
public void terminateEvaluation() throws DebugException;
/**
* Returns whether the currently executing <code>IEvaluationRunnable</code>
* supports termination. An IEvaluationRunnable supports termination if it
* implements <code>ITerminate</code>
*
* @return whether the current evaluation supports termination
* @since 2.1
*/
public boolean canTerminateEvaluation();
/**
* Returns a Java object for the monitor for which this thread is currently
* waiting or <code>null</code>.
*
* @return IJavaObject the contended monitor object or <code>null</code> if
* this thread is not waiting on a monitor.
* @exception DebugException
* if an exception occurs while retrieving the contended
* monitor.
* @since 2.1
*/
public IJavaObject getContendedMonitor() throws DebugException;
/**
* Returns the monitors owned by this thread or <code>null</code> if this
* thread owns no monitors.
*
* @return the owned monitors
* @exception DebugException
* if an exception occurs while retrieving the owned monitors
* of this thread.
* @since 2.1
*/
public IJavaObject[] getOwnedMonitors() throws DebugException;
/**
* Returns whether this threads owns at least one monitor.
*
* @return boolean whether this thread owns a monitor
* @exception DebugException
* if an exception occurs determining if there are owned
* monitors.
* @since 2.1
*/
public boolean hasOwnedMonitors() throws DebugException;
/**
* Request to stops this thread with the given exception.<br>
* The result will be the same as calling
* java.lang.Thread#stop(java.lang.Throwable).<br>
* If the thread is suspended when the method is called, the thread must be
* resumed to complete the action.<br>
*
* <em>exception</em> must represent an exception.
*
* @param exception
* the exception to throw.
* @exception DebugException
* if the request fails
* @since 3.0
* @see java.lang.Thread#stop(java.lang.Throwable)
*/
public void stop(IJavaObject exception) throws DebugException;
/**
* Returns the thread group this thread belongs to or <code>null</code> if
* none.
*
* @return thread group or <code>null</code>
* @throws DebugException
* if the thread group cannot be computed
* @since 3.2
*/
public IJavaThreadGroup getThreadGroup() throws DebugException;
/**
* Returns whether this thread is a daemon thread.
*
* @return whether this thread is a daemon thread
* @throws DebugException
* if an exception occurs while determining status
* @since 3.3
*/
public boolean isDaemon() throws DebugException;
/**
* Returns the number of frames in this thread.
*
* @return number of stack frames
* @throws DebugException
* if an exception occurs while retrieving the count
* @since 3.3
*/
public int getFrameCount() throws DebugException;
/**
* Returns the object reference associated with this thread.
*
* @return thread object reference
* @throws DebugException
* if unable to retrieve an object reference
* @since 3.6
*/
public IJavaObject getThreadObject() throws DebugException;
}