--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/jdi-overview.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,88 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html>
+ <head>
+ <title>Java(tm) Debug Interface</title>
+ </head>
+ <body>
+ The Java<sup><font size="-2">TM</font></sup>
+ Debug Interface (JDI) is a high level Java
+API providing information useful for debuggers and similiar
+systems needing access to the running state of a (usually remote)
+virtual machine.
+<p>
+ The JDI provides introspective
+access to a running virtual machine's state, Class, Array,
+Interface, and primitive types, and instances of those
+types.
+<P>
+The JDI also provides explicit control over
+a virtual machine's execution. The ability to suspend
+and resume threads, and to set breakpoints, watchpoints, ...
+Notification
+of exceptions, class loading, thread creation...
+The ability to inspect a suspended thread's state,
+local variables, stack backtrace...
+<p>
+JDI is the highest-layer of the Java Platform Debugger Architecture (JPDA).
+For more information on the Java Platform Debugger Architecture, see the
+<a href="{@docRoot}/../../../../technotes/guides/jpda/index.html">
+Java Platform Debugger Architecture documentation</a>
+for this release and the
+<a href="http://java.sun.com/products/jpda">Java Platform Debugger Architecture website</a>.
+<p>
+<font size="+1"><b>Global Exceptions:</b></font>
+<p>
+This section documents exceptions which apply to the entire API and are thus
+not documented on individual methods.
+
+ <blockquote>
+ <p>
+ <b>{@link com.sun.jdi.VMMismatchException}</b>
+ <p>
+ Any method on a {@link com.sun.jdi.Mirror} that takes a <code>Mirror</code> as an
+ parameter directly or indirectly (e.g., as a element in a <code>List</code>) will
+ throw {@link com.sun.jdi.VMMismatchException} if the mirrors are from different
+ virtual machines.
+ <p>
+ <b>{@link java.lang.NullPointerException}</b>
+ <p>
+ Any method which takes a {@link java.lang.Object} as an parameter will throw
+ {@link java.lang.NullPointerException} if null is passed directly or indirectly
+ -- unless null is explicitly mentioned as a valid parameter.
+ <p>
+ </blockquote>
+ NOTE: The exceptions below may be thrown whenever the specified
+ conditions are met but a guarantee that they are thrown only
+ exists when a valid result cannot be returned.
+ <blockquote>
+ <p>
+ <b>{@link com.sun.jdi.VMDisconnectedException}</b>
+ <p>
+ Any method on {@link com.sun.jdi.ObjectReference}, {@link com.sun.jdi.ReferenceType},
+ {@link com.sun.jdi.request.EventRequest}, {@link com.sun.jdi.StackFrame}, or
+ {@link com.sun.jdi.VirtualMachine} or which takes one of these directly or indirectly
+ as an parameter may throw {@link com.sun.jdi.VMDisconnectedException} if the target VM
+ is disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is available
+ to be read from the {@link com.sun.jdi.event.EventQueue}.
+ <p>
+ <b>{@link com.sun.jdi.VMOutOfMemoryException}</b>
+ <p>
+ Any method on {@link com.sun.jdi.ObjectReference}, {@link com.sun.jdi.ReferenceType},
+ {@link com.sun.jdi.request.EventRequest}, {@link com.sun.jdi.StackFrame}, or
+ {@link com.sun.jdi.VirtualMachine} or which takes one of these directly or indirectly
+ as an parameter may throw {@link com.sun.jdi.VMOutOfMemoryException} if the target
+ VM has run out of memory.
+ <p>
+ <b>{@link com.sun.jdi.ObjectCollectedException}</b>
+ <p>
+ Any method on {@link com.sun.jdi.ObjectReference} or which directly or indirectly takes
+ <code>ObjectReference</code> as parameter may throw {@link com.sun.jdi.ObjectCollectedException}
+ if the mirrored object has been garbage collected.
+ <p>
+ Any method on {@link com.sun.jdi.ReferenceType} or which directly or indirectly takes
+ <code>ReferenceType</code> as parameter may throw {@link com.sun.jdi.ObjectCollectedException}
+ if the mirrored type has been unloaded.
+
+ </blockquote>
+ </body>
+</html>