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 org.eclipse.core.runtime.IProgressMonitor;
013: import org.eclipse.debug.core.DebugException;
014: import org.eclipse.debug.core.model.IFilteredStep;
015: import org.eclipse.debug.core.model.IThread;
016:
017: /**
018: * A thread in a Java virtual machine.
019: * <p>
020: * Clients are not intended to implement this interface.
021: * </p>
022: * @see org.eclipse.debug.core.model.IThread
023: */
024: public interface IJavaThread extends IThread, IFilteredStep {
025:
026: /**
027: * Status code indicating a request failed because a thread
028: * was not suspended.
029: */
030: public static final int ERR_THREAD_NOT_SUSPENDED = 100;
031:
032: /**
033: * Status code indicating a request to perform a message send
034: * failed because a thread was already performing a message send.
035: *
036: * @see IJavaObject#sendMessage(String, String, IJavaValue[], IJavaThread, boolean)
037: * @see IJavaClassType#sendMessage(String, String, IJavaValue[], IJavaThread)
038: * @see IJavaClassType#newInstance(String, IJavaValue[], IJavaThread)
039: */
040: public static final int ERR_NESTED_METHOD_INVOCATION = 101;
041:
042: /**
043: * Status code indicating a request to perform a message send
044: * failed because a thread was not suspended by a step or
045: * breakpoint event. When a thread is suspended explicitly via
046: * the <code>suspend()</code> method, it is not able to perform
047: * method invocations (this is a JDI limitation).
048: *
049: * @see IJavaObject#sendMessage(String, String, IJavaValue[], IJavaThread, boolean)
050: * @see IJavaClassType#sendMessage(String, String, IJavaValue[], IJavaThread)
051: * @see IJavaClassType#newInstance(String, IJavaValue[], IJavaThread)
052: */
053: public static final int ERR_INCOMPATIBLE_THREAD_STATE = 102;
054:
055: /**
056: * Returns whether this thread is a system thread.
057: *
058: * @return whether this thread is a system thread
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: * </ul>
065: */
066: boolean isSystemThread() throws DebugException;
067:
068: /**
069: * Returns whether any of the stack frames associated with this thread
070: * are running code in the VM that is out of synch with the code
071: * in the workspace.
072: *
073: * @return whether this thread is out of synch with the workspace.
074: * @exception DebugException if this method fails. Reasons include:
075: * <ul>
076: * <li>Failure communicating with the VM. The DebugException's
077: * status code contains the underlying exception responsible for
078: * the failure.</li>
079: * @since 2.0
080: */
081: boolean isOutOfSynch() throws DebugException;
082:
083: /**
084: * Returns whether this thread may be running code in the VM that
085: * is out of synch with the code in the workspace.
086: *
087: * @return whether this thread may be out of synch with the workspace.
088: * @exception DebugException if this method fails. Reasons include:
089: * <ul>
090: * <li>Failure communicating with the VM. The DebugException's
091: * status code contains the underlying exception responsible for
092: * the failure.</li>
093: * @since 2.0
094: */
095: boolean mayBeOutOfSynch() throws DebugException;
096:
097: /**
098: * Returns whether this thread is currently performing
099: * an evaluation.
100: *
101: * @return whether this thread is currently performing
102: * an evaluation
103: * @since 2.0
104: */
105: boolean isPerformingEvaluation();
106:
107: /**
108: * Returns the name of the thread group this thread belongs to,
109: * or <code>null</code> if none.
110: *
111: * @return thread group name, or <code>null</code> if none
112: * @exception DebugException if this method fails. Reasons include:
113: * <ul>
114: * <li>Failure communicating with the VM. The DebugException's
115: * status code contains the underlying exception responsible for
116: * the failure.</li>
117: * </ul>
118: */
119: String getThreadGroupName() throws DebugException;
120:
121: /**
122: * Returns a variable with the given name, or <code>null</code> if
123: * unable to resolve a variable with the name, or if this
124: * thread is not currently suspended.
125: * <p>
126: * Variable lookup works only when a thread is suspended.
127: * Lookup is performed in all stack frames, in a top-down
128: * order, returning the first successful match, or <code>null</code>
129: * if no match is found.
130: * </p>
131: * @param variableName the name of the variable to search for
132: * @return a variable, or <code>null</code> if none
133: * @exception DebugException if this method fails. Reasons include:
134: * <ul>
135: * <li>Failure communicating with the VM. The DebugException's
136: * status code contains the underlying exception responsible for
137: * the failure.</li>
138: * </ul>
139: */
140: IJavaVariable findVariable(String variableName)
141: throws DebugException;
142:
143: /**
144: * Invokes the given evaluation with the specified progress
145: * monitor. This thread fires a resume event
146: * when the evaluation begins, and a suspend event when the evaluation
147: * completes or throws an exception. The events are given a detail
148: * as specified by <code>evaluationDetail</code> (one of
149: * <code>DebugEvent.EVALUATION</code> or
150: * <code>DebugEvent.EVALUATION_IMPLICIT</code>).
151: *
152: * @param evaluation the evaluation to perform
153: * @param monitor progress monitor (may be <code>null</code>
154: * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
155: * <code>DebugEvent.EVALUATION_IMPLICIT</code>
156: * @param hitBreakpoints whether or not breakpoints should be honored
157: * in this thread during the evaluation. If <code>false</code>, breakpoints
158: * hit in this thread during the evaluation will be ignored.
159: * @exception DebugException if an exception occurs performing
160: * the evaluation
161: * @since 2.0
162: */
163: public void runEvaluation(IEvaluationRunnable evaluation,
164: IProgressMonitor monitor, int evaluationDetail,
165: boolean hitBreakpoints) throws DebugException;
166:
167: /**
168: * Queues the given runnable with the list of runnables associated with this thread.
169: * Runnables are executed asynchronously in a separate thread. This method should be
170: * used to execute any code which performs an operation like a method invocation.
171: *
172: * @param runnable the runnable to execute.
173: * @since 2.1
174: */
175: public void queueRunnable(Runnable runnable);
176:
177: /**
178: * Attempts to terminate the currently executing <code>IEvaluationRunnable</code>
179: * in this thread, if any.
180: *
181: * Evaluations may be composed of a series of instructions.
182: * Terminating an evaluation means stopping the evaluation after
183: * the current instruction completes. A single instruction (such as a method invocation)
184: * cannot be interrupted.
185: *
186: * @exception DebugException if an exception occurs while
187: * terminating the evaluation.
188: * @since 2.1
189: */
190: public void terminateEvaluation() throws DebugException;
191:
192: /**
193: * Returns whether the currently executing <code>IEvaluationRunnable</code>
194: * supports termination. An IEvaluationRunnable supports termination
195: * if it implements <code>ITerminate</code>
196: *
197: * @return whether the current evaluation supports termination
198: * @since 2.1
199: */
200: public boolean canTerminateEvaluation();
201:
202: /**
203: * Returns a Java object for the monitor for
204: * which this thread is currently waiting or <code>null</code>.
205: *
206: * @return IJavaObject the contended monitor object or <code>null</code> if this
207: * thread is not waiting on a monitor.
208: * @exception DebugException if an exception occurs while
209: * retrieving the contended monitor.
210: * @since 2.1
211: */
212: public IJavaObject getContendedMonitor() throws DebugException;
213:
214: /**
215: * Returns the monitors owned by this thread or <code>null</code>
216: * if this thread owns no monitors.
217: *
218: * @return the owned monitors
219: * @exception DebugException if an exception occurs while retrieving
220: * the owned monitors of this thread.
221: * @since 2.1
222: */
223: public IJavaObject[] getOwnedMonitors() throws DebugException;
224:
225: /**
226: * Returns whether this threads owns at least one monitor.
227: *
228: * @return boolean whether this thread owns a monitor
229: * @exception DebugException if an exception occurs determining
230: * if there are owned monitors.
231: * @since 2.1
232: */
233: public boolean hasOwnedMonitors() throws DebugException;
234:
235: /**
236: * Request to stops this thread with the given exception.<br>
237: * The result will be the same as calling java.lang.Thread#stop(java.lang.Throwable).<br>
238: * If the thread is suspended when the method is called, the thread must be
239: * resumed to complete the action.<br>
240: *
241: * <em>exception</em> must represent an exception.
242: *
243: * @param exception the exception to throw.
244: * @exception DebugException
245: * @since 3.0
246: * @see java.lang.Thread#stop(java.lang.Throwable)
247: */
248: public void stop(IJavaObject exception) throws DebugException;
249:
250: /**
251: * Returns the thread group this thread belongs to or <code>null</code> if none.
252: *
253: * @return thread group or <code>null</code>
254: * @throws DebugException
255: * @since 3.2
256: */
257: public IJavaThreadGroup getThreadGroup() throws DebugException;
258:
259: /**
260: * Returns whether this thread is a daemon thread.
261: *
262: * @return whether this thread is a daemon thread
263: * @throws DebugException if an exception occurs while determining status
264: * @since 3.3
265: */
266: public boolean isDaemon() throws DebugException;
267:
268: /**
269: * Returns the number of frames in this thread.
270: *
271: * @return number of stack frames
272: * @throws DebugException if an exception occurs while retrieving the count
273: * @since 3.3
274: */
275: public int getFrameCount() throws DebugException;
276:
277: }
|