|
1 /* |
|
2 * Copyright 1998-2004 Sun Microsystems, Inc. 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. Sun designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
22 * CA 95054 USA or visit www.sun.com if you need additional information or |
|
23 * have any questions. |
|
24 */ |
|
25 |
|
26 package com.sun.jdi; |
|
27 |
|
28 import com.sun.jdi.connect.*; |
|
29 import com.sun.jdi.connect.spi.Connection; |
|
30 import java.util.List; |
|
31 import java.io.IOException; |
|
32 |
|
33 /** |
|
34 * A manager of connections to target virtual machines. The |
|
35 * VirtualMachineManager allows one application to debug |
|
36 * multiple target VMs. (Note that the converse is not |
|
37 * supported; a target VM can be debugged by only one |
|
38 * debugger application.) This interface |
|
39 * contains methods to manage connections |
|
40 * to remote target VMs and to obtain the {@link VirtualMachine} |
|
41 * mirror for available target VMs. |
|
42 * <p> |
|
43 * Connections can be made using one of several different |
|
44 * {@link com.sun.jdi.connect.Connector} objects. Each connector encapsulates |
|
45 * a different way of connecting the debugger with a target VM. |
|
46 * <p> |
|
47 * The VirtualMachineManager supports many different scenarios for |
|
48 * connecting a debugger to a virtual machine. Four examples |
|
49 * are presented in the table below. The |
|
50 * examples use the command line syntax in Sun's implementation. |
|
51 * Some {@link com.sun.jdi.connect.Connector} implementations may require slightly |
|
52 * different handling than presented below. |
|
53 * <p> |
|
54 * <TABLE BORDER WIDTH="75%" SUMMARY="Four scenarios for connecting a debugger |
|
55 * to a virtual machine"> |
|
56 * <TR> |
|
57 * <TH scope=col>Scenario</TH> |
|
58 * <TH scope=col>Description</TH> |
|
59 * <TR> |
|
60 * <TD>Debugger launches target VM (simplest, most-common scenario)</TD> |
|
61 * |
|
62 * <TD>Debugger calls the |
|
63 * {@link com.sun.jdi.connect.LaunchingConnector#launch(java.util.Map)} |
|
64 * method of the default connector, obtained with {@link #defaultConnector}. The |
|
65 * target VM is launched, and a connection between that VM and the |
|
66 * debugger is established. A {@link VirtualMachine} mirror is returned. |
|
67 * <P>Or, for more control |
|
68 * <UL> |
|
69 * <LI> |
|
70 * Debugger selects a connector from the list returned by |
|
71 * {@link #launchingConnectors} with desired characteristics |
|
72 * (for example, transport type, etc.). |
|
73 * <LI> |
|
74 * Debugger calls the |
|
75 * {@link com.sun.jdi.connect.LaunchingConnector#launch(java.util.Map)} |
|
76 * method of the selected connector. The |
|
77 * target VM is launched, and a connection between that VM and the |
|
78 * debugger is established. A {@link VirtualMachine} mirror is returned. |
|
79 * </UL> |
|
80 * </TD> |
|
81 * </TR> |
|
82 * <TR> |
|
83 * <TD>Debugger attaches to previously-running VM</TD> |
|
84 * <TD> |
|
85 * <UL> |
|
86 * <LI> |
|
87 * Target VM is launched using the options |
|
88 * <code>-agentlib:jdwp=transport=xxx,server=y</code> |
|
89 * </LI> |
|
90 * <LI> |
|
91 * Target VM generates and outputs the tranport-specific address at which it will |
|
92 * listen for a connection.</LI> |
|
93 * <LI> |
|
94 * Debugger is launched. Debugger selects a connector in the list |
|
95 * returned by {@link #attachingConnectors} matching the transport with |
|
96 * the name "xxx". |
|
97 * <LI> |
|
98 * Debugger presents the default connector parameters (obtained through |
|
99 * {@link com.sun.jdi.connect.Connector#defaultArguments()}) to the end user, |
|
100 * allowing the user to |
|
101 * fill in the transport-specific address generated by the target VM. |
|
102 * <LI> |
|
103 * Debugger calls the {@link com.sun.jdi.connect.AttachingConnector#attach(java.util.Map)} method |
|
104 * of the selected to attach to the target VM. A {@link VirtualMachine} |
|
105 * mirror is returned. |
|
106 * </UL> |
|
107 * </TD> |
|
108 * </TR> |
|
109 * |
|
110 * <TR> |
|
111 * <TD>Target VM attaches to previously-running debugger</TD> |
|
112 * <TD> |
|
113 * <LI> |
|
114 * At startup, debugger selects one or more connectors from |
|
115 * the list returned by {@link #listeningConnectors} for one or more |
|
116 * transports.</LI> |
|
117 * <LI> |
|
118 * Debugger calls the {@link com.sun.jdi.connect.ListeningConnector#startListening(java.util.Map)} method for each selected |
|
119 * connector. For each call, a transport-specific address string is |
|
120 * generated and returned. The debugger makes the transport names and |
|
121 * corresponding address strings available to the end user. |
|
122 * <LI> |
|
123 * Debugger calls |
|
124 * {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} |
|
125 * for each selected connector to wait for |
|
126 * a target VM to connect.</LI> |
|
127 * <LI> |
|
128 * Later, target VM is launched by end user with the options |
|
129 * <code>-agentlib:jdwp=transport=xxx,address=yyy</code> |
|
130 * where "xxx" the transport for one of the connectors selected by the |
|
131 * the debugger and "yyy" |
|
132 * is the address generated by |
|
133 * {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} for that |
|
134 * transport.</LI> |
|
135 * <LI> |
|
136 * Debugger's call to {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} returns |
|
137 * a {@link VirtualMachine} mirror.</LI> |
|
138 * </TD> |
|
139 * </TR> |
|
140 * |
|
141 * <TR> |
|
142 * <TD>Target VM launches debugger (sometimes called "Just-In-Time" debugging)</TD> |
|
143 * <TD> |
|
144 * <LI> |
|
145 * Target VM is launched with the options |
|
146 * <code>-agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y</code> |
|
147 * </LI> |
|
148 * <LI> |
|
149 * Later, an uncaught exception is thrown in the target VM. The target |
|
150 * VM generates the tranport-specific address at which it will |
|
151 * listen for a connection. |
|
152 * <LI>Target VM launches the debugger with the following items concatenated |
|
153 * together (separated by spaces) to form the command line: |
|
154 * <UL> |
|
155 * <LI> The launch= value |
|
156 * <LI> The transport= value |
|
157 * <LI> The generated transport-specific address at which VM is listening for |
|
158 * debugger connection. |
|
159 * </UL> |
|
160 * <LI> |
|
161 * Upon launch, debugger selects a connector in the list |
|
162 * returned by {@link #attachingConnectors} matching the transport with |
|
163 * the name "xxx". |
|
164 * <LI> |
|
165 * Debugger changes the default connector parameters (obtained through |
|
166 * {@link com.sun.jdi.connect.Connector#defaultArguments()}) to specify |
|
167 * the transport specific address at which the VM is listenig. Optionally, |
|
168 * other connector arguments can be presented to the user. |
|
169 * <LI> |
|
170 * Debugger calls the |
|
171 * {@link com.sun.jdi.connect.AttachingConnector#attach(java.util.Map)} method |
|
172 * of the selected to attach to the target VM. A {@link VirtualMachine} |
|
173 * mirror is returned. |
|
174 * </TD> |
|
175 * </TR> |
|
176 * </TABLE> |
|
177 * |
|
178 * <p> Connectors are created at start-up time. That is, they |
|
179 * are created the first time that {@link |
|
180 * com.sun.jdi.Bootstrap#virtualMachineManager()} is invoked. |
|
181 * The list of all Connectors created at start-up time can be |
|
182 * obtained from the VirtualMachineManager by invoking the |
|
183 * {@link #allConnectors allConnectors} method. |
|
184 * |
|
185 * <p> Connectors are created at start-up time if they are |
|
186 * installed on the platform. In addition, Connectors are created |
|
187 * automatically by the VirtualMachineManager to encapsulate any |
|
188 * {@link com.sun.jdi.connect.spi.TransportService} implementations |
|
189 * that are installed on the platform. These two mechanisms for |
|
190 * creating Connectors are described here. |
|
191 * |
|
192 * <p> A Connector is installed on the platform if it is installed |
|
193 * in a jar file that is visible to the defining class loader of |
|
194 * the {@link com.sun.jdi.connect.Connector} type, |
|
195 * and that jar file contains a provider configuration file named |
|
196 * <tt>com.sun.jdi.connect.Connector</tt> in the resource directory |
|
197 * <tt>META-INF/services</tt>, and the provider configuration file |
|
198 * lists the full-qualified class name of the Connector |
|
199 * implementation. A Connector is a class that implements the |
|
200 * {@link com.sun.jdi.connect.Connector Connector} interface. More |
|
201 * appropriately the class implements one of the specific Connector |
|
202 * types, namely {@link com.sun.jdi.connect.AttachingConnector |
|
203 * AttachingConnector}, {@link com.sun.jdi.connect.ListeningConnector |
|
204 * ListeningConnector}, or {@link com.sun.jdi.connect.LaunchingConnector |
|
205 * LaunchingConnector}. The format of the provider configuration file |
|
206 * is one fully-qualified class name per line. Space and tab characters |
|
207 * surrounding each class, as well as blank lines are ignored. The |
|
208 * comment character is <tt>'#'</tt> (<tt>0x23</tt>), and on each |
|
209 * line all characters following the first comment character are |
|
210 * ignored. The file must be encoded in UTF-8. |
|
211 * |
|
212 * <p> At start-up time the VirtualMachineManager attempts to load |
|
213 * and instantiate (using the no-arg constructor) each class listed |
|
214 * in the provider configuration file. Exceptions thrown when loading |
|
215 * or creating the Connector are caught and ignored. In other words, |
|
216 * the start-up process continues despite of errors. |
|
217 * |
|
218 * <p> In addition to Connectors installed on the platform the |
|
219 * VirtualMachineManager will also create Connectors to encapsulate |
|
220 * any {@link com.sun.jdi.connect.spi.TransportService} implementations |
|
221 * that are installed on the platform. A TransportService is |
|
222 * installed on the platform if it installed in a jar file that is |
|
223 * visible to the defining class loader for the |
|
224 * {@link com.sun.jdi.connect.spi.TransportService} type, and that jar |
|
225 * file contains a provider configuration file named |
|
226 * <tt>com.sun.jdi.connect.spi.TransportService</tt> in the resource |
|
227 * directory <tt>META-INF/services</tt>, and the provider |
|
228 * configuration file lists the the full-qualified class name of the |
|
229 * TransportService implementation. A TransportService is a concrete |
|
230 * sub-class of {@link com.sun.jdi.connect.spi.TransportService |
|
231 * TransportService}. The format of the provider configuration file |
|
232 * is the same as the provider configuration file for Connectors |
|
233 * except that each class listed must be the fully-qualified class |
|
234 * name of a class that implements the TransportService interface. |
|
235 * |
|
236 * <p> For each TransportService installed on the platform, the |
|
237 * VirtualMachineManager creates a corresponding |
|
238 * {@link com.sun.jdi.connect.AttachingConnector} and |
|
239 * {@link com.sun.jdi.connect.ListeningConnector}. These |
|
240 * Connectors are created to encapsulate a {@link |
|
241 * com.sun.jdi.connect.Transport Transport} that in turn |
|
242 * encapsulates the TransportService. |
|
243 * The AttachingConnector will be named based on the name of the |
|
244 * transport service concatenated with the string <tt>Attach</tt>. |
|
245 * For example, if the transport service {@link |
|
246 * com.sun.jdi.connect.spi.TransportService#name() name()} method |
|
247 * returns <tt>telepathic</tt> then the AttachingConnector will |
|
248 * be named <tt>telepathicAttach</tt>. Similiarly the ListeningConnector |
|
249 * will be named with the string <tt>Listen</tt> tagged onto the |
|
250 * name of the transport service. The {@link |
|
251 * com.sun.jdi.connect.Connector#description() description()} method |
|
252 * of both the AttachingConnector, and the ListeningConnector, will |
|
253 * delegate to the {@link com.sun.jdi.connect.spi.TransportService#description() |
|
254 * description()} method of the underlying transport service. Both |
|
255 * the AttachingConnector and the ListeningConnector will have two |
|
256 * Connector {@link com.sun.jdi.connect.Connector$Argument Arguments}. |
|
257 * A {@link com.sun.jdi.connect.Connector$StringArgument StringArgument} |
|
258 * named <tt>address</tt> is the connector argument to specify the |
|
259 * address to attach too, or to listen on. A |
|
260 * {@link com.sun.jdi.connect.Connector$IntegerArgument IntegerArgument} |
|
261 * named <tt>timeout</tt> is the connector argument to specify the |
|
262 * timeout when attaching, or accepting. The timeout connector may be |
|
263 * ignored depending on if the transport service supports an attach |
|
264 * timeout or accept timeout. |
|
265 * |
|
266 * <p> Initialization of the virtual machine manager will fail, that is |
|
267 * {@link com.sun.jdi.Bootstrap#virtualMachineManager()} will throw an |
|
268 * error if the virtual machine manager is unable to create any |
|
269 * connectors. |
|
270 * |
|
271 * @author Gordon Hirsch |
|
272 * @since 1.3 |
|
273 */ |
|
274 public interface VirtualMachineManager { |
|
275 |
|
276 /** |
|
277 * Identifies the default connector. This connector should |
|
278 * be used as the launching connector when selection of a |
|
279 * connector with specific characteristics is unnecessary. |
|
280 * |
|
281 * @return the default {@link com.sun.jdi.connect.LaunchingConnector} |
|
282 */ |
|
283 LaunchingConnector defaultConnector(); |
|
284 |
|
285 /** |
|
286 * Returns the list of known {@link com.sun.jdi.connect.LaunchingConnector} objects. |
|
287 * Any of the returned objects can be used to launch a new target |
|
288 * VM and immediately create a {@link VirtualMachine} mirror for it. |
|
289 * |
|
290 * Note that a target VM launched by a launching connector is not |
|
291 * guaranteed to be stable until after the {@link com.sun.jdi.event.VMStartEvent} has been |
|
292 * received. |
|
293 * @return a list of {@link com.sun.jdi.connect.LaunchingConnector} objects. |
|
294 */ |
|
295 List<LaunchingConnector> launchingConnectors(); |
|
296 |
|
297 /** |
|
298 * Returns the list of known {@link com.sun.jdi.connect.AttachingConnector} objects. |
|
299 * Any of the returned objects can be used to attach to an existing target |
|
300 * VM and create a {@link VirtualMachine} mirror for it. |
|
301 * |
|
302 * @return a list of {@link com.sun.jdi.connect.AttachingConnector} objects. |
|
303 */ |
|
304 List<AttachingConnector> attachingConnectors(); |
|
305 |
|
306 /** |
|
307 * Returns the list of known {@link com.sun.jdi.connect.ListeningConnector} objects. |
|
308 * Any of the returned objects can be used to listen for a |
|
309 * connection initiated by a target VM |
|
310 * and create a {@link VirtualMachine} mirror for it. |
|
311 * |
|
312 * @return a list of {@link com.sun.jdi.connect.ListeningConnector} objects. |
|
313 */ |
|
314 List<ListeningConnector> listeningConnectors(); |
|
315 |
|
316 /** |
|
317 * Returns the list of all known {@link com.sun.jdi.connect.Connector} objects. |
|
318 * |
|
319 * @return a list of {@link com.sun.jdi.connect.Connector} objects. |
|
320 */ |
|
321 List<Connector> allConnectors(); |
|
322 |
|
323 /** |
|
324 * Lists all target VMs which are connected to the debugger. |
|
325 * The list includes {@link VirtualMachine} instances for |
|
326 * any target VMs which initiated a connection |
|
327 * and any |
|
328 * target VMs to which this manager has initiated a connection. |
|
329 * A target VM will remain in this list |
|
330 * until the VM is disconnected. |
|
331 * {@link com.sun.jdi.event.VMDisconnectEvent} is placed in the event queue |
|
332 * after the VM is removed from the list. |
|
333 * |
|
334 * @return a list of {@link VirtualMachine} objects, each mirroring |
|
335 * a target VM. |
|
336 */ |
|
337 List<VirtualMachine> connectedVirtualMachines(); |
|
338 |
|
339 /** |
|
340 * Returns the major version number of the JDI interface. |
|
341 * See {@link VirtualMachine#version} target VM version and |
|
342 * information and |
|
343 * {@link VirtualMachine#description} more version information. |
|
344 * |
|
345 * @return the integer major version number. |
|
346 */ |
|
347 int majorInterfaceVersion(); |
|
348 |
|
349 /** |
|
350 * Returns the minor version number of the JDI interface. |
|
351 * See {@link VirtualMachine#version} target VM version and |
|
352 * information and |
|
353 * {@link VirtualMachine#description} more version information. |
|
354 * |
|
355 * @return the integer minor version number |
|
356 */ |
|
357 int minorInterfaceVersion(); |
|
358 |
|
359 /** |
|
360 * Create a virtual machine mirror for a target VM. |
|
361 * |
|
362 * <p> Creates a virtual machine mirror for a target VM |
|
363 * for which a {@link com.sun.jdi.connect.spi.Connection Connection} |
|
364 * already exists. A Connection is created when a {@link |
|
365 * com.sun.jdi.connect.Connector Connector} establishes |
|
366 * a connection and successfully handshakes with a target VM. |
|
367 * A Connector can then use this method to create a virtual machine |
|
368 * mirror to represent the composite state of the target VM. |
|
369 * |
|
370 * <p> The <tt>process</tt> argument specifies the |
|
371 * {@link java.lang.Process} object for the taget VM. It may be |
|
372 * specified as <tt>null</tt>. If the target VM is launched |
|
373 * by a {@link com.sun.jdi.connect.LaunchingConnector |
|
374 * LaunchingConnector} the <tt>process</tt> argument should be |
|
375 * specified, otherwise calling {@link com.sun.jdi.VirtualMachine#process()} |
|
376 * on the created virtual machine will return <tt>null</tt>. |
|
377 * |
|
378 * <p> This method exists so that Connectors may create |
|
379 * a virtual machine mirror when a connection is established |
|
380 * to a target VM. Only developers creating new Connector |
|
381 * implementations should need to make direct use of this |
|
382 * method. </p> |
|
383 * |
|
384 * @param connection |
|
385 * The open connection to the target VM. |
|
386 * |
|
387 * @param process |
|
388 * If launched, the {@link java.lang.Process} object for |
|
389 * the target VM. <tt>null</tt> if not launched. |
|
390 * |
|
391 * @return new virtual machine representing the target VM. |
|
392 * |
|
393 * @throws IOException |
|
394 * if an I/O error occurs |
|
395 * |
|
396 * @throws IllegalStateException |
|
397 * if the connection is not open |
|
398 * |
|
399 * @see com.sun.jdi.connect.spi.Connection#isOpen() |
|
400 * @see com.sun.jdi.VirtualMachine#process() |
|
401 * |
|
402 * @since 1.5 |
|
403 */ |
|
404 VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException; |
|
405 |
|
406 /** |
|
407 * Creates a new virtual machine. |
|
408 * |
|
409 * <p> This convenience method works as if by invoking {@link |
|
410 * #createVirtualMachine(Connection, Process)} method and |
|
411 * specifying <tt>null</tt> as the <tt>process</tt> argument. |
|
412 * |
|
413 * <p> This method exists so that Connectors may create |
|
414 * a virtual machine mirror when a connection is established |
|
415 * to a target VM. Only developers creating new Connector |
|
416 * implementations should need to make direct use of this |
|
417 * method. </p> |
|
418 * |
|
419 * @return the new virtual machine |
|
420 * |
|
421 * @throws IOException |
|
422 * if an I/O error occurs |
|
423 * |
|
424 * @throws IllegalStateException |
|
425 * if the connection is not open |
|
426 * |
|
427 * @since 1.5 |
|
428 */ |
|
429 VirtualMachine createVirtualMachine(Connection connection) throws IOException; |
|
430 } |