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.debug.core.DebugException;
013: import org.eclipse.debug.core.model.IDebugTarget;
014: import org.eclipse.debug.core.model.IStepFilters;
015:
016: /**
017: * A Java virtual machine.
018: * <p>
019: * Clients are not intended to implement this interface.
020: * </p>
021: * @see IDebugTarget
022: * @see org.eclipse.core.runtime.IAdaptable
023: */
024:
025: public interface IJavaDebugTarget extends IDebugTarget, IStepFilters {
026: /**
027: * Searches for and returns a variable with the given name,
028: * or <code>null</code> if unable to resolve a variable with the name.
029: * <p>
030: * Variable lookup works only when a debug target has one or more
031: * threads suspended. Lookup is performed in each suspended thread,
032: * returning the first successful match, or <code>null</code> if no
033: * match if found. If this debug target has no suspended threads,
034: * <code>null</code> is returned.
035: * </p>
036: * @param variableName name of the variable
037: * @return a variable with the given name, or <code>null</code> if none
038: * @exception DebugException if this method fails. Reasons include:
039: * <ul>
040: * <li>Failure communicating with the VM. The DebugException's
041: * status code contains the underlying exception responsible for
042: * the failure.</li>
043: * </ul>
044: */
045: public abstract IJavaVariable findVariable(String variableName)
046: throws DebugException;
047:
048: /**
049: * Returns the types loaded in this debug target with the given fully
050: * qualified name, or <code>null</code> of no type with the given
051: * name is loaded.
052: *
053: * @param name fully qualified name of type, for example
054: * <code>java.lang.String</code>
055: * @return the types with the given name, or <code>null</code>
056: * @exception DebugException if this method fails. Reasons include:
057: * <ul>
058: * <li>Failure communicating with the VM. The DebugException's
059: * status code contains the underlying exception responsible for
060: * the failure.</li>
061: * </ul>
062: */
063: public abstract IJavaType[] getJavaTypes(String name)
064: throws DebugException;
065:
066: /**
067: * Returns a value from this target that corresponds to the given boolean.
068: * The returned value can be used for setting and comparing against a value
069: * retrieved from this debug target.
070: *
071: * @param value a boolean from which to create a value
072: * @return a corresponding value from this target
073: */
074: public abstract IJavaValue newValue(boolean value);
075:
076: /**
077: * Returns a value from this target that corresponds to the given byte.
078: * The returned value can be used for setting and comparing against a value
079: * retrieved from this debug target.
080: *
081: * @param value a byte from which to create a value
082: * @return a corresponding value from this target
083: */
084: public abstract IJavaValue newValue(byte value);
085:
086: /**
087: * Returns a value from this target that corresponds to the given char.
088: * The returned value can be used for setting and comparing against a value
089: * retrieved from this debug target.
090: *
091: * @param value a char from which to create a value
092: * @return a corresponding value from this target
093: */
094: public abstract IJavaValue newValue(char value);
095:
096: /**
097: * Returns a value from this target that corresponds to the given double.
098: * The returned value can be used for setting and comparing against a value
099: * 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: /**
175: * Returns whether any of the threads associated with this debug target
176: * are running code in the VM that is out of synch with the code
177: * in the workspace.
178: *
179: * @return whether this debug target is out of synch with the workspace.
180: * @exception DebugException if this method fails. Reasons include:
181: * <ul>
182: * <li>Failure communicating with the VM. The DebugException's
183: * status code contains the underlying exception responsible for
184: * the failure.</li>
185: */
186: public abstract boolean isOutOfSynch() throws DebugException;
187:
188: /**
189: * Returns whether any of the threads associated with this debug target
190: * may be running code in the VM that is out of synch with the code
191: * in the workspace.
192: *
193: * @return whether this debug target may be out of synch with the workspace.
194: * @exception DebugException if this method fails. Reasons include:
195: * <ul>
196: * <li>Failure communicating with the VM. The DebugException's
197: * status code contains the underlying exception responsible for
198: * the failure.</li>
199: */
200: public abstract boolean mayBeOutOfSynch() throws DebugException;
201:
202: /**
203: * Returns whether this target supports hot code replace.
204: *
205: * @return whether this target supports hot code replace
206: */
207: public boolean supportsHotCodeReplace();
208:
209: /**
210: * Returns whether this target is currently performing a hot code replace.
211: *
212: * @return whether this target is currently performing a hot code replace
213: * @since 2.1
214: */
215: public boolean isPerformingHotCodeReplace();
216:
217: /**
218: * Returns whether this target supports instance breakpoints.
219: *
220: * @return whether this target supports instance breakpoints
221: * @since 2.1
222: */
223: public boolean supportsInstanceBreakpoints();
224:
225: /**
226: * Returns whether synthetic methods are filtered
227: * when stepping, if step filters are enabled.
228: *
229: * @return whether synthetic methods are filtered
230: * when stepping
231: */
232: public abstract boolean isFilterSynthetics();
233:
234: /**
235: * Sets whether synthetic methods are filtered
236: * when stepping.
237: *
238: * @param filter whether to synthetic methods are filtered
239: * when stepping
240: */
241: public abstract void setFilterSynthetics(boolean filter);
242:
243: /**
244: * Returns whether static initializers are filtered
245: * when stepping, if step filters are enabled.
246: *
247: * @return whether static initializers are filtered
248: * when stepping
249: */
250: public abstract boolean isFilterStaticInitializers();
251:
252: /**
253: * Sets whether to filter static initializers when
254: * stepping.
255: *
256: * @param filter whether to filter static initializers when
257: * stepping
258: */
259: public abstract void setFilterStaticInitializers(boolean filter);
260:
261: /**
262: * Returns whether constructors are filtered when stepping,
263: * if step filters are enabled.
264: *
265: * @return whether constructors are filtered when stepping
266: */
267: public abstract boolean isFilterConstructors();
268:
269: /**
270: * Sets whether to filter constructors when stepping.
271: *
272: * @param filter whether to filter constructors when stepping
273: */
274: public abstract void setFilterConstructors(boolean filter);
275:
276: /**
277: * Returns the list of active step filters in this target.
278: * The list is a collection of Strings. Each string is the
279: * fully qualified name/pattern of a type/package to filter
280: * when stepping. For example <code>java.lang.*</code> or
281: * <code>java.lang.String</code>.
282: *
283: * @return the list of active step filters, or <code>null</code>
284: */
285: public abstract String[] getStepFilters();
286:
287: /**
288: * Sets the list of active step filters in this target.
289: * The list is a collection of Strings. Each string is the
290: * fully qualified name/pattern of a type/package to filter
291: * when stepping. For example <code>java.lang.*</code> or
292: * <code>java.lang.String</code>.
293: *
294: * @param list active step filters, or <code>null</code>
295: */
296: public abstract void setStepFilters(String[] list);
297:
298: /**
299: * Returns whether this debug target supports a request timeout -
300: * a maximum time for a JDI request to receive a response. This option
301: * is only supported by the Eclipse JDI implementation.
302: *
303: * @return whether this debug target supports a request timeout
304: */
305: public boolean supportsRequestTimeout();
306:
307: /**
308: * Sets the timeout value for JDI requests in milliseconds. Has
309: * no effect if this target does not support a request timeout.
310: *
311: * @param timeout the communication timeout, in milliseconds
312: */
313: public void setRequestTimeout(int timeout);
314:
315: /**
316: * Returns the timeout value for JDI requests in milliseconds,
317: * or -1 if not supported.
318: *
319: * @return timeout value, in milliseconds, or -1 if not supported
320: */
321: public int getRequestTimeout();
322:
323: /**
324: * Returns whether this target supports providing monitor information.
325: *
326: * @return whether this target supports providing monitor information.
327: * @since 2.1
328: */
329: public boolean supportsMonitorInformation();
330:
331: /**
332: * Returns whether this target supports access watchpoints.
333: *
334: * @return whether this target supports access watchpoints
335: * @since 3.0
336: */
337: public boolean supportsAccessWatchpoints();
338:
339: /**
340: * Returns whether this target supports modification watchpoints.
341: *
342: * @return whether this target supports modification watchpoints
343: * @since 3.0
344: */
345: public boolean supportsModificationWatchpoints();
346:
347: /**
348: * Set the default stratum used in this debug target.
349: *
350: * @param stratum the new default stratum, or <code>null</code> to indicate per-class
351: * default stratum
352: * @since 3.0
353: */
354: public void setDefaultStratum(String stratum);
355:
356: /**
357: * Return the default stratum used in this the target, or <code>null</code> to indicate
358: * a per-class default stratum.
359: *
360: * @return the default stratum, or <code>null</code> to indicate a per-class default
361: * stratum
362: * @see #setDefaultStratum(String)
363: * @since 3.0
364: */
365: public String getDefaultStratum();
366:
367: /**
368: * Returns the top level thread groups in this target. Top level thread groups
369: * do not have a parent.
370: *
371: * @return top level thread groups
372: * @throws DebugException
373: * @since 3.2
374: */
375: public IJavaThreadGroup[] getRootThreadGroups()
376: throws DebugException;
377:
378: /**
379: * Returns all thread groups in this target.
380: *
381: * @return all thread groups in this target
382: * @throws DebugException
383: * @since 3.2
384: */
385: public IJavaThreadGroup[] getAllThreadGroups()
386: throws DebugException;
387:
388: /**
389: * Returns whether this VM supports instance and reference retrieval
390: * for types and objects.
391: *
392: * @return whether this VM supports instance and reference retrieval
393: * for types and objects
394: * @since 3.3
395: */
396: public boolean supportsInstanceRetrieval();
397:
398: /**
399: * Returns whether this VM supports the ability to force an early return
400: * from methods.
401: *
402: * @return whether this VM can force an early return from methods
403: * @since 3.3
404: * @see IJavaThread
405: */
406: public boolean supportsForceReturn();
407:
408: /**
409: * Returns whether this VM supports the ability to enable and disable garbage
410: * collection of individual objects.
411: *
412: * @return whether this VM supports the ability to enable and disable garbage
413: * collection of individual objects
414: * @see IJavaObject
415: * @since 3.4
416: */
417: public boolean supportsSelectiveGarbageCollection();
418:
419: /**
420: * Returns the name of the underlying virtual machine as defined by the system
421: * property <code>java.vm.name</code>.
422: *
423: * @return virtual machine name
424: * @exception DebugException if retrieving the name fails
425: * @since 3.4
426: */
427: public String getVMName() throws DebugException;
428:
429: /**
430: * Returns the version of the underlying virtual machine as defined by the system
431: * property <code>java.version</code>.
432: *
433: * @return <code>java.version</code> system property
434: * @exception DebugException if retrieving the version property fails
435: * @since 3.4
436: */
437: public String getVersion() throws DebugException;
438: }
|