1 /*
2 * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 /**
27 * Defines the Java Debug Interface.
28 * <p>
29 * The Java Debug Interface (JDI) is a high level Java API providing
30 * information useful for debuggers and similar systems needing access to the
31 * running state of a (usually remote) virtual machine.
32 * <p>
33 * JDI provides introspective access to a running virtual machine's state,
34 * Class, Array, Interface, and primitive types, and instances of those types.
35 * <p>
36 * JDI also provides explicit control over a virtual machine's execution.
37 * The ability to suspend and resume threads, and to set breakpoints,
38 * watchpoints, etc. Notification of exceptions, class loading, thread
39 * creation, etc. The ability to inspect a suspended thread's state, local
40 * variables, stack backtrace, etc.
41 * <p>
42 * JDI is the highest-layer of the
43 * <a href="{@docRoot}/../specs/jpda/jpda.html">
44 * Java Platform Debugger Architecture (JPDA)</a>.
45 * <p>
46 * This module includes a simple command-line debugger,
47 * <em>{@index jdb jdb tool}</em>.
48 *
49 * <h2>Global Exceptions</h2>
50 * <p>
51 * This section documents exceptions which apply to the entire API and are thus
52 * not documented on individual methods.
53 * <blockquote>
54 * <p>
55 * <b>{@link com.sun.jdi.VMMismatchException}</b>
56 * <p>
57 * Any method on a {@link com.sun.jdi.Mirror} that takes a
58 * {@code Mirror} as an parameter directly or indirectly (e.g., as a
59 * element in a {@code List}) will throw {@link
60 * com.sun.jdi.VMMismatchException} if the mirrors are from different virtual
61 * machines.
62 * <p>
63 * <b>{@link java.lang.NullPointerException}</b>
64 * <p>
65 * Any method which takes a {@link java.lang.Object} as an parameter will
66 * throw {@link java.lang.NullPointerException} if null is passed directly or
67 * indirectly -- unless null is explicitly mentioned as a valid parameter.
68 * </blockquote>
69 * NOTE: The exceptions below may be thrown whenever the specified conditions
70 * are met but a guarantee that they are thrown only exists when a valid result
71 * cannot be returned.
72 * <blockquote>
73 * <p>
74 * <b>{@link com.sun.jdi.VMDisconnectedException}</b>
75 * <p>
76 * Any method on {@link com.sun.jdi.ObjectReference}, {@link
77 * com.sun.jdi.ReferenceType}, {@link com.sun.jdi.request.EventRequest},
78 * {@link com.sun.jdi.StackFrame}, or {@link com.sun.jdi.VirtualMachine} or
79 * which takes one of these directly or indirectly as an parameter may throw
80 * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
81 * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been
82 * or is available to be read from the {@link com.sun.jdi.event.EventQueue}.
83 * <p>
84 * <b>{@link com.sun.jdi.VMOutOfMemoryException}</b>
85 * <p>
86 * Any method on {@link com.sun.jdi.ObjectReference}, {@link
87 * com.sun.jdi.ReferenceType}, {@link com.sun.jdi.request.EventRequest},
88 * {@link com.sun.jdi.StackFrame}, or {@link com.sun.jdi.VirtualMachine} or
89 * which takes one of these directly or indirectly as an parameter may throw
90 * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of
91 * memory.
92 * <p>
93 * <b>{@link com.sun.jdi.ObjectCollectedException}</b>
94 * <p>
95 * Any method on {@link com.sun.jdi.ObjectReference} or which directly or
96 * indirectly takes {@code ObjectReference} as parameter may throw
97 * {@link com.sun.jdi.ObjectCollectedException} if the mirrored object has
98 * been garbage collected.
99 * <p>
100 * Any method on {@link com.sun.jdi.ReferenceType} or which directly or
101 * indirectly takes {@code ReferenceType} as parameter may throw {@link
102 * com.sun.jdi.ObjectCollectedException} if the mirrored type has been
103 * unloaded.
104 * </blockquote>
105 *
106 *
107 * @toolGuide jdb
108 *
109 * @provides com.sun.jdi.connect.Connector
110 *
111 * @uses com.sun.jdi.connect.Connector
112 * @uses com.sun.jdi.connect.spi.TransportService
113 *
114 * @moduleGraph
115 * @since 9
116 * @see <a href="{@docRoot}/../specs/jpda/jpda.html">
117 * Java Platform Debugger Architecture (JPDA)</a>
118 */
119 module jdk.jdi {
120 requires jdk.attach;
121 requires jdk.jdwp.agent;
122
123 exports com.sun.jdi;
124 exports com.sun.jdi.connect;
125 exports com.sun.jdi.connect.spi;
126 exports com.sun.jdi.event;
127 exports com.sun.jdi.request;
128
129 uses com.sun.jdi.connect.Connector;
130 uses com.sun.jdi.connect.spi.TransportService;
131
132 // windows shared memory connector providers are added at build time
133 provides com.sun.jdi.connect.Connector with
134 com.sun.tools.jdi.ProcessAttachingConnector,
135 com.sun.tools.jdi.RawCommandLineLauncher,
136 com.sun.tools.jdi.SocketAttachingConnector,
137 com.sun.tools.jdi.SocketListeningConnector,
138 com.sun.tools.jdi.SunCommandLineLauncher;
139 }