IJavaDebugTarget


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.debug.core.DebugException;
15  import org.eclipse.debug.core.model.IDebugTarget;
16  import org.eclipse.debug.core.model.IStepFilters;
17  
18  /**
19   * A Java virtual machine.
20   * <p>
21   * Clients are not intended to implement this interface.
22   * </p>
23   * @see IDebugTarget
24   * @see org.eclipse.core.runtime.IAdaptable 
25   */
26  
27  public interface IJavaDebugTarget extends IDebugTarget, IStepFilters {
28      /**
29       * Searches for and returns a variable with the given name,
30       * or <code>null</code> if unable to resolve a variable with the name.
31       * <p>
32       * Variable lookup works only when a debug target has one or more
33       * threads suspended. Lookup is performed in each suspended thread,
34       * returning the first successful match, or <code>null</code> if no
35       * match if found. If this debug target has no suspended threads,
36       * <code>null</code> is returned.
37       * </p>
38       * @param variableName name of the variable
39       * @return a variable with the given name, or <code>null</code> if none
40       * @exception DebugException if this method fails.  Reasons include:
41       * <ul>
42       * <li>Failure communicating with the VM.  The DebugException's
43       * status code contains the underlying exception responsible for
44       * the failure.</li>
45       * </ul>
46       */
47      public abstract IJavaVariable findVariable(String   variableName) throws DebugException;
48      
49      /**
50       * Returns the types loaded in this debug target with the given fully
51       * qualified name, or <code>null</code> of no type with the given
52       * name is loaded.
53       * 
54       * @param name fully qualified name of type, for example
55       *  <code>java.lang.String</code>
56       * @return the types with the given name, or <code>null</code>
57       * @exception DebugException if this method fails.  Reasons include:
58       * <ul>
59       * <li>Failure communicating with the VM.  The DebugException's
60       * status code contains the underlying exception responsible for
61       * the failure.</li>
62       * </ul>
63       */
64      public abstract IJavaType[] getJavaTypes(String   name) throws DebugException;
65  
66      /**
67       * Returns a value from this target that corresponds to the given boolean.
68       * The returned value can be used for setting and comparing against a value 
69       * retrieved from this debug target.
70       * 
71       * @param value a boolean from which to create a value
72       * @return a corresponding value from this target
73       */ 
74      public abstract IJavaValue newValue(boolean value); 
75  
76      /**
77       * Returns a value from this target that corresponds to the given byte.
78       * The returned value can be used for setting and comparing against a value 
79       * retrieved from this debug target.
80       * 
81       * @param value a byte from which to create a value
82       * @return a corresponding value from this target
83       */ 
84      public abstract IJavaValue newValue(byte value);    
85  
86      /**
87       * Returns a value from this target that corresponds to the given char.
88       * The returned value can be used for setting and comparing against a value 
89       * retrieved from this debug target.
90       * 
91       * @param value a char from which to create a value
92       * @return a corresponding value from this target
93       */ 
94      public abstract IJavaValue newValue(char value);
95      
96      /**
97       * Returns a value from this target that corresponds to the given double.
98       * The returned value can be used for setting and comparing against a value 
99       * retrieved from this debug target.
100      * 
101      * @param value a double from which to create a value
102      * @return a corresponding value from this target
103      */ 
104     public abstract IJavaValue newValue(double value);  
105     
106     /**
107      * Returns a value from this target that corresponds to the given float.
108      * The returned value can be used for setting and comparing against a value 
109      * retrieved from this debug target.
110      * 
111      * @param value a float from which to create a value
112      * @return a corresponding value from this target
113      */ 
114     public abstract IJavaValue newValue(float value);       
115                 
116     /**
117      * Returns a value from this target that corresponds to the given int.
118      * The returned value can be used for setting and comparing against a value 
119      * retrieved from this debug target.
120      * 
121      * @param value an int from which to create a value
122      * @return a corresponding value from this target
123      */ 
124     public abstract IJavaValue newValue(int value);
125     
126     /**
127      * Returns a value from this target that corresponds to the given long.
128      * The returned value can be used for setting and comparing against a value 
129      * retrieved from this debug target.
130      * 
131      * @param value a long from which to create a value
132      * @return a corresponding value from this target
133      */ 
134     public abstract IJavaValue newValue(long value);    
135     
136     /**
137      * Returns a value from this target that corresponds to the given short.
138      * The returned value can be used for setting and comparing against a value 
139      * retrieved from this debug target.
140      * 
141      * @param value a short from which to create a value
142      * @return a corresponding value from this target
143      */ 
144     public abstract IJavaValue newValue(short value);
145     
146     /**
147      * Returns a value from this target that corresponds to the given string.
148      * The returned value can be used for setting and comparing against a value 
149      * retrieved from this debug target.
150      * 
151      * @param value a string from which to create a value
152      * @return a corresponding value from this target
153      */ 
154     public abstract IJavaValue newValue(String   value);      
155     
156     /**
157      * Returns a value from this target that corresponds to <code>null</code>.
158      * The returned value can be used for setting
159      * and comparing against a value retrieved from this debug target.
160      * 
161      * @return a value corresponding to <code>null</code>
162      */ 
163     public abstract IJavaValue nullValue();
164     
165     /**
166      * Returns a value from this target that corresponds to
167      * <code>void</code>. The returned value can be used for setting
168      * and comparing against a value retrieved from this debug target.
169      * 
170      * @return a value corresponding to <code>void</code>
171      */ 
172     public abstract IJavaValue voidValue();
173     /**
174      * Returns whether any of the threads associated with this debug target
175      * are running code in the VM that is out of synch with the code
176      * in the workspace.
177      * 
178      * @return whether this debug target is out of synch with the workspace.
179      * @exception DebugException if this method fails.  Reasons include:
180      * <ul>
181      * <li>Failure communicating with the VM.  The DebugException's
182      * status code contains the underlying exception responsible for
183      * the failure.</li>
184      */
185     public abstract boolean isOutOfSynch() throws DebugException;
186     /**
187      * Returns whether any of the threads associated with this debug target
188      * may be running code in the VM that is out of synch with the code
189      * in the workspace.
190      * 
191      * @return whether this debug target may be out of synch with the workspace.
192      * @exception DebugException if this method fails.  Reasons include:
193      * <ul>
194      * <li>Failure communicating with the VM.  The DebugException's
195      * status code contains the underlying exception responsible for
196      * the failure.</li>
197      */
198     public abstract boolean mayBeOutOfSynch() throws DebugException;
199     /**
200      * Returns whether this target supports hot code replace.
201      * 
202      * @return whether this target supports hot code replace
203      */
204     public boolean supportsHotCodeReplace();
205     /**
206      * Returns whether this target is currently performing a hot code replace.
207      * 
208      * @return whether this target is currently performing a hot code replace
209      * @since 2.1
210      */
211     public boolean isPerformingHotCodeReplace();
212     /**
213      * Returns whether this target supports instance breakpoints.
214      * 
215      * @return whether this target supports instance breakpoints
216      * @since 2.1
217      */
218     public boolean supportsInstanceBreakpoints();
219         
220     /**
221      * Returns whether synthetic methods are filtered
222      * when stepping, if step filters are enabled.
223      * 
224      * @return whether synthetic methods are filtered
225      * when stepping
226      */
227     public abstract boolean isFilterSynthetics();
228     
229     /**
230      * Sets whether synthetic methods are filtered
231      * when stepping.
232      * 
233      * @param filter whether to synthetic methods are filtered
234      * when stepping
235      */
236     public abstract void setFilterSynthetics(boolean filter);
237     
238     /**
239      * Returns whether static initializers are filtered
240      * when stepping, if step filters are enabled.
241      * 
242      * @return whether static initializers are filtered
243      * when stepping
244      */
245     public abstract boolean isFilterStaticInitializers();
246     
247     /**
248      * Sets whether to filter static initializers when
249      * stepping.
250      * 
251      * @param filter whether to filter static initializers when
252      * stepping
253      */
254     public abstract void setFilterStaticInitializers(boolean filter);
255     
256     /**
257      * Returns whether constructors are filtered when stepping,
258      * if step filters are enabled.
259      * 
260      * @return whether constructors are filtered when stepping
261      */
262     public abstract boolean isFilterConstructors();
263     
264     /**
265      * Sets whether to filter constructors when stepping.
266      * 
267      * @param filter whether to filter constructors when stepping
268      */
269     public abstract void setFilterConstructors(boolean filter);
270     
271     /**
272      * Returns the list of active step filters in this target.
273      * The list is a collection of Strings. Each string is the 
274      * fully qualified name/pattern of a type/package to filter
275      * when stepping. For example <code>java.lang.*</code> or
276      * <code>java.lang.String</code>.
277      * 
278      * @return the list of active step filters, or <code>null</code>
279      */
280     public abstract String  [] getStepFilters();
281     
282     /**
283      * Sets the list of active step filters in this target.
284      * The list is a collection of Strings. Each string is the 
285      * fully qualified name/pattern of a type/package to filter
286      * when stepping. For example <code>java.lang.*</code> or
287      * <code>java.lang.String</code>.
288      * 
289      * @param list active step filters, or <code>null</code>
290      */
291     public abstract void setStepFilters(String  [] list);
292     
293     /**
294      * Returns whether this debug target supports a request timeout - 
295      * a maximum time for a JDI request to receive a response. This option
296      * is only supported by the Eclipse JDI implementation.
297      * 
298      * @return  whether this debug target supports a request timeout
299      */
300     public boolean supportsRequestTimeout();
301     
302     /**
303      * Sets the timeout value for JDI requests in milliseconds. Has
304      * no effect if this target does not support a request timeout.
305      * 
306      * @param timeout the communication timeout, in milliseconds
307      */
308     public void setRequestTimeout(int timeout);
309     
310     /**
311      * Returns the timeout value for JDI requests in milliseconds,
312      * or -1 if not supported.
313      * 
314      * @return timeout value, in milliseconds, or -1 if not supported
315      */
316     public int getRequestTimeout();
317     
318     /**
319      * Returns whether this target supports providing monitor information.
320      * 
321      * @return whether this target supports providing monitor information.
322      * @since 2.1
323      */
324     public boolean supportsMonitorInformation();
325     
326     /**
327      * Returns whether this target supports access watchpoints.
328      * 
329      * @return whether this target supports access watchpoints
330      * @since 3.0
331      */
332     public boolean supportsAccessWatchpoints();
333     
334     /**
335      * Returns whether this target supports modification watchpoints.
336      * 
337      * @return whether this target supports modification watchpoints
338      * @since 3.0
339      */
340     public boolean supportsModificationWatchpoints();   
341     
342     /**
343      * Set the default stratum used in this debug target.
344      * 
345      * @param stratum the new default stratum, or <code>null</code> to indicate per-class
346      *  default stratum
347      * @since 3.0
348      */
349     public void setDefaultStratum(String   stratum);
350     
351     /**
352      * Return the default stratum used in this the target, or <code>null</code> to indicate
353      * a per-class default stratum.
354      * 
355      * @return the default stratum, or <code>null</code> to indicate a per-class default
356      *  stratum
357      * @see #setDefaultStratum(String)
358      * @since 3.0
359      */
360     public String   getDefaultStratum();
361     
362     /**
363      * Returns the top level thread groups in this target. Top level thread groups
364      * do not have a parent.
365      * 
366      * @return top level thread groups
367      * @throws DebugException
368      * @since 3.2
369      */
370     public IJavaThreadGroup[] getRootThreadGroups() throws DebugException;
371     
372     /**
373      * Returns all thread groups in this target.
374      * 
375      * @return all thread groups in this target
376      * @throws DebugException
377      * @since 3.2
378      */
379     public IJavaThreadGroup[] getAllThreadGroups() throws DebugException;
380     
381     /**
382      * Returns whether this VM supports instance and reference retrieval
383      * for types and objects.
384      * 
385      * @return whether this VM supports instance and reference retrieval
386      * for types and objects
387      * @since 3.3
388      */
389     public boolean supportsInstanceRetrieval();
390     
391     /**
392      * Returns whether this VM supports the ability to force an early return
393      * from methods.
394      * 
395      * @return whether this VM can force an early return from methods
396      * @since 3.3
397      * @see IJavaThread
398      */
399     public boolean supportsForceReturn();
400 }
401
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags