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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags