KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > debug > core > IJavaThread


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.jdt.debug.core;
12
13
14 import org.eclipse.core.runtime.IProgressMonitor;
15 import org.eclipse.debug.core.DebugException;
16 import org.eclipse.debug.core.model.IFilteredStep;
17 import org.eclipse.debug.core.model.IThread;
18
19 /**
20  * A thread in a Java virtual machine.
21  * <p>
22  * Clients are not intended to implement this interface.
23  * </p>
24  * @see org.eclipse.debug.core.model.IThread
25  */

26 public interface IJavaThread extends IThread, IFilteredStep {
27     
28     /**
29      * Status code indicating a request failed because a thread
30      * was not suspended.
31      */

32     public static final int ERR_THREAD_NOT_SUSPENDED = 100;
33     
34     /**
35      * Status code indicating a request to perform a message send
36      * failed because a thread was already performing a message send.
37      *
38      * @see IJavaObject#sendMessage(String, String, IJavaValue[], IJavaThread, boolean)
39      * @see IJavaClassType#sendMessage(String, String, IJavaValue[], IJavaThread)
40      * @see IJavaClassType#newInstance(String, IJavaValue[], IJavaThread)
41      */

42     public static final int ERR_NESTED_METHOD_INVOCATION = 101;
43
44     /**
45      * Status code indicating a request to perform a message send
46      * failed because a thread was not suspended by a step or
47      * breakpoint event. When a thread is suspended explicitly via
48      * the <code>suspend()</code> method, it is not able to perform
49      * method invocations (this is a JDI limitation).
50      *
51      * @see IJavaObject#sendMessage(String, String, IJavaValue[], IJavaThread, boolean)
52      * @see IJavaClassType#sendMessage(String, String, IJavaValue[], IJavaThread)
53      * @see IJavaClassType#newInstance(String, IJavaValue[], IJavaThread)
54      */

55     public static final int ERR_INCOMPATIBLE_THREAD_STATE = 102;
56     
57     /**
58      * Returns whether this thread is a system thread.
59      *
60      * @return whether this thread is a system thread
61      * @exception DebugException if this method fails. Reasons include:
62      * <ul>
63      * <li>Failure communicating with the VM. The DebugException's
64      * status code contains the underlying exception responsible for
65      * the failure.</li>
66      * </ul>
67      */

68     boolean isSystemThread() throws DebugException;
69     /**
70      * Returns whether any of the stack frames associated with this thread
71      * are running code in the VM that is out of synch with the code
72      * in the workspace.
73      *
74      * @return whether this thread is out of synch with the workspace.
75      * @exception DebugException if this method fails. Reasons include:
76      * <ul>
77      * <li>Failure communicating with the VM. The DebugException's
78      * status code contains the underlying exception responsible for
79      * the failure.</li>
80      * @since 2.0
81      */

82     boolean isOutOfSynch() throws DebugException;
83     /**
84      * Returns whether this thread may be running code in the VM that
85      * is out of synch with the code in the workspace.
86      *
87      * @return whether this thread may be out of synch with the workspace.
88      * @exception DebugException if this method fails. Reasons include:
89      * <ul>
90      * <li>Failure communicating with the VM. The DebugException's
91      * status code contains the underlying exception responsible for
92      * the failure.</li>
93      * @since 2.0
94      */

95     boolean mayBeOutOfSynch() throws DebugException;
96     /**
97      * Returns whether this thread is currently performing
98      * an evaluation.
99      *
100      * @return whether this thread is currently performing
101      * an evaluation
102      * @since 2.0
103      */

104     boolean isPerformingEvaluation();
105     /**
106      * Returns the name of the thread group this thread belongs to,
107      * or <code>null</code> if none.
108      *
109      * @return thread group name, or <code>null</code> if none
110      * @exception DebugException if this method fails. Reasons include:
111      * <ul>
112      * <li>Failure communicating with the VM. The DebugException's
113      * status code contains the underlying exception responsible for
114      * the failure.</li>
115      * </ul>
116      */

117     String JavaDoc getThreadGroupName() throws DebugException;
118     
119     /**
120      * Returns a variable with the given name, or <code>null</code> if
121      * unable to resolve a variable with the name, or if this
122      * thread is not currently suspended.
123      * <p>
124      * Variable lookup works only when a thread is suspended.
125      * Lookup is performed in all stack frames, in a top-down
126      * order, returning the first successful match, or <code>null</code>
127      * if no match is found.
128      * </p>
129      * @param variableName the name of the variable to search for
130      * @return a variable, or <code>null</code> if none
131      * @exception DebugException if this method fails. Reasons include:
132      * <ul>
133      * <li>Failure communicating with the VM. The DebugException's
134      * status code contains the underlying exception responsible for
135      * the failure.</li>
136      * </ul>
137      */

138     IJavaVariable findVariable(String JavaDoc variableName) throws DebugException;
139     
140     /**
141      * Invokes the given evaluation with the specified progress
142      * monitor. This thread fires a resume event
143      * when the evaluation begins, and a suspend event when the evaluation
144      * completes or throws an exception. The events are given a detail
145      * as specified by <code>evaluationDetail</code> (one of
146      * <code>DebugEvent.EVALUATION</code> or
147      * <code>DebugEvent.EVALUATION_IMPLICIT</code>).
148      *
149      * @param evaluation the evaluation to perform
150      * @param monitor progress monitor (may be <code>null</code>
151      * @param evaluationDetail one of <code>DebugEvent.EVALUATION</code> or
152      * <code>DebugEvent.EVALUATION_IMPLICIT</code>
153      * @param hitBreakpoints whether or not breakpoints should be honored
154      * in this thread during the evaluation. If <code>false</code>, breakpoints
155      * hit in this thread during the evaluation will be ignored.
156      * @exception DebugException if an exception occurs performing
157      * the evaluation
158      * @since 2.0
159      */

160     public void runEvaluation(IEvaluationRunnable evaluation, IProgressMonitor monitor, int evaluationDetail, boolean hitBreakpoints) throws DebugException;
161
162     /**
163      * Queues the given runnable with the list of runnables associated with this thread.
164      * Runnables are executed asynchronously in a separate thread. This method should be
165      * used to execute any code which performs an operation like a method invocation.
166      *
167      * @param runnable the runnable to execute.
168      * @since 2.1
169      */

170     public void queueRunnable(Runnable JavaDoc runnable);
171
172     /**
173      * Attempts to terminate the currently executing <code>IEvaluationRunnable</code>
174      * in this thread, if any.
175      *
176      * Evaluations may be composed of a series of instructions.
177      * Terminating an evaluation means stopping the evaluation after
178      * the current instruction completes. A single instruction (such as a method invocation)
179      * cannot be interrupted.
180      *
181      * @exception DebugException if an exception occurs while
182      * terminating the evaluation.
183      * @since 2.1
184      */

185     public void terminateEvaluation() throws DebugException;
186     /**
187      * Returns whether the currently executing <code>IEvaluationRunnable</code>
188      * supports termination. An IEvaluationRunnable supports termination
189      * if it implements <code>ITerminate</code>
190      *
191      * @return whether the current evaluation supports termination
192      * @since 2.1
193      */

194     public boolean canTerminateEvaluation();
195     
196     /**
197      * Returns a Java object for the monitor for
198      * which this thread is currently waiting or <code>null</code>.
199      *
200      * @return IJavaObject the contended monitor object or <code>null</code> if this
201      * thread is not waiting on a monitor.
202      * @exception DebugException if an exception occurs while
203      * retrieving the contended monitor.
204      * @since 2.1
205      */

206     public IJavaObject getContendedMonitor() throws DebugException;
207     
208     /**
209      * Returns the monitors owned by this thread or <code>null</code>
210      * if this thread owns no monitors.
211      *
212      * @return the owned monitors
213      * @exception DebugException if an exception occurs while retrieving
214      * the owned monitors of this thread.
215      * @since 2.1
216      */

217     public IJavaObject[] getOwnedMonitors() throws DebugException;
218     
219     /**
220      * Returns whether this threads owns at least one monitor.
221      *
222      * @return boolean whether this thread owns a monitor
223      * @exception DebugException if an exception occurs determining
224      * if there are owned monitors.
225      * @since 2.1
226      */

227     public boolean hasOwnedMonitors() throws DebugException;
228     
229     /**
230      * Request to stops this thread with the given exception.<br>
231      * The result will be the same as calling java.lang.Thread#stop(java.lang.Throwable).<br>
232      * If the thread is suspended when the method is called, the thread must be
233      * resumed to complete the action.<br>
234      *
235      * <em>exception</em> must represent an exception.
236      *
237      * @param exception the exception to throw.
238      * @exception DebugException
239      * @since 3.0
240      * @see java.lang.Thread#stop(java.lang.Throwable)
241      */

242     public void stop(IJavaObject exception) throws DebugException;
243     
244     /**
245      * Returns the thread group this thread belongs to or <code>null</code> if none.
246      *
247      * @return thread group or <code>null</code>
248      * @throws DebugException
249      * @since 3.2
250      */

251     public IJavaThreadGroup getThreadGroup() throws DebugException;
252     
253     /**
254      * Returns whether this thread is a daemon thread.
255      *
256      * @return whether this thread is a daemon thread
257      * @throws DebugException if an exception occurs while determining status
258      * @since 3.3
259      */

260     public boolean isDaemon() throws DebugException;
261     
262     /**
263      * Returns the number of frames in this thread.
264      *
265      * @return number of stack frames
266      * @throws DebugException if an exception occurs while retrieving the count
267      * @since 3.3
268      */

269     public int getFrameCount() throws DebugException;
270
271 }
272
Popular Tags