1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2 <html>
3 <head>
4 <title>Java(tm) Debug Interface</title>
5 </head>
6 <body>
7 The Java<sup><font size="-2">TM</font></sup>
8 Debug Interface (JDI) is a high level Java
9 API providing information useful for debuggers and similar
10 systems needing access to the running state of a (usually remote)
11 virtual machine.
12 <p>
13 The JDI provides introspective
14 access to a running virtual machine's state, Class, Array,
15 Interface, and primitive types, and instances of those
16 types.
17 <P>
18 The JDI also provides explicit control over
19 a virtual machine's execution. The ability to suspend
20 and resume threads, and to set breakpoints, watchpoints, ...
21 Notification
22 of exceptions, class loading, thread creation...
23 The ability to inspect a suspended thread's state,
24 local variables, stack backtrace...
25 <p>
26 JDI is the highest-layer of the Java Platform Debugger Architecture (JPDA).
27 For more information on the Java Platform Debugger Architecture, see the
28 <a href="{@docRoot}/../../../../technotes/guides/jpda/index.html">
29 Java Platform Debugger Architecture documentation</a>
30 for this release and the
31 <a href="http://java.sun.com/products/jpda">Java Platform Debugger Architecture website</a>.
32 <p>
33 <font size="+1"><b>Global Exceptions:</b></font>
34 <p>
35 This section documents exceptions which apply to the entire API and are thus
36 not documented on individual methods.
37
38 <blockquote>
39 <p>
40 <b>{@link com.sun.jdi.VMMismatchException}</b>
41 <p>
42 Any method on a {@link com.sun.jdi.Mirror} that takes a <code>Mirror</code> as an
43 parameter directly or indirectly (e.g., as a element in a <code>List</code>) will
44 throw {@link com.sun.jdi.VMMismatchException} if the mirrors are from different
45 virtual machines.
46 <p>
47 <b>{@link java.lang.NullPointerException}</b>
48 <p>
49 Any method which takes a {@link java.lang.Object} as an parameter will throw
50 {@link java.lang.NullPointerException} if null is passed directly or indirectly
51 -- unless null is explicitly mentioned as a valid parameter.
52 </blockquote>
53 NOTE: The exceptions below may be thrown whenever the specified
54 conditions are met but a guarantee that they are thrown only
55 exists when a valid result cannot be returned.
56 <blockquote>
57 <p>
58 <b>{@link com.sun.jdi.VMDisconnectedException}</b>
59 <p>
60 Any method on {@link com.sun.jdi.ObjectReference}, {@link com.sun.jdi.ReferenceType},
61 {@link com.sun.jdi.request.EventRequest}, {@link com.sun.jdi.StackFrame}, or
62 {@link com.sun.jdi.VirtualMachine} or which takes one of these directly or indirectly
63 as an parameter may throw {@link com.sun.jdi.VMDisconnectedException} if the target VM
64 is disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is available
65 to be read from the {@link com.sun.jdi.event.EventQueue}.
66 <p>
67 <b>{@link com.sun.jdi.VMOutOfMemoryException}</b>
68 <p>
69 Any method on {@link com.sun.jdi.ObjectReference}, {@link com.sun.jdi.ReferenceType},
70 {@link com.sun.jdi.request.EventRequest}, {@link com.sun.jdi.StackFrame}, or
71 {@link com.sun.jdi.VirtualMachine} or which takes one of these directly or indirectly
72 as an parameter may throw {@link com.sun.jdi.VMOutOfMemoryException} if the target
73 VM has run out of memory.
74 <p>
75 <b>{@link com.sun.jdi.ObjectCollectedException}</b>
76 <p>
77 Any method on {@link com.sun.jdi.ObjectReference} or which directly or indirectly takes
78 <code>ObjectReference</code> as parameter may throw {@link com.sun.jdi.ObjectCollectedException}
79 if the mirrored object has been garbage collected.
80 <p>
81 Any method on {@link com.sun.jdi.ReferenceType} or which directly or indirectly takes
82 <code>ReferenceType</code> as parameter may throw {@link com.sun.jdi.ObjectCollectedException}
83 if the mirrored type has been unloaded.
84
85 </blockquote>
86 </body>
87 </html>