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