1 /*
2 * Copyright (c) 1998, 2004, 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 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 @jdk.Supported
275 public interface VirtualMachineManager {
276
277 /**
278 * Identifies the default connector. This connector should
279 * be used as the launching connector when selection of a
280 * connector with specific characteristics is unnecessary.
281 *
282 * @return the default {@link com.sun.jdi.connect.LaunchingConnector}
283 */
284 LaunchingConnector defaultConnector();
285
286 /**
287 * Returns the list of known {@link com.sun.jdi.connect.LaunchingConnector} objects.
288 * Any of the returned objects can be used to launch a new target
289 * VM and immediately create a {@link VirtualMachine} mirror for it.
290 *
291 * Note that a target VM launched by a launching connector is not
292 * guaranteed to be stable until after the {@link com.sun.jdi.event.VMStartEvent} has been
293 * received.
294 * @return a list of {@link com.sun.jdi.connect.LaunchingConnector} objects.
295 */
296 List<LaunchingConnector> launchingConnectors();
297
298 /**
299 * Returns the list of known {@link com.sun.jdi.connect.AttachingConnector} objects.
300 * Any of the returned objects can be used to attach to an existing target
301 * VM and create a {@link VirtualMachine} mirror for it.
302 *
303 * @return a list of {@link com.sun.jdi.connect.AttachingConnector} objects.
304 */
305 List<AttachingConnector> attachingConnectors();
306
307 /**
308 * Returns the list of known {@link com.sun.jdi.connect.ListeningConnector} objects.
309 * Any of the returned objects can be used to listen for a
310 * connection initiated by a target VM
311 * and create a {@link VirtualMachine} mirror for it.
312 *
313 * @return a list of {@link com.sun.jdi.connect.ListeningConnector} objects.
314 */
315 List<ListeningConnector> listeningConnectors();
316
317 /**
318 * Returns the list of all known {@link com.sun.jdi.connect.Connector} objects.
319 *
320 * @return a list of {@link com.sun.jdi.connect.Connector} objects.
321 */
322 List<Connector> allConnectors();
323
324 /**
325 * Lists all target VMs which are connected to the debugger.
326 * The list includes {@link VirtualMachine} instances for
327 * any target VMs which initiated a connection
328 * and any
329 * target VMs to which this manager has initiated a connection.
330 * A target VM will remain in this list
331 * until the VM is disconnected.
332 * {@link com.sun.jdi.event.VMDisconnectEvent} is placed in the event queue
333 * after the VM is removed from the list.
334 *
335 * @return a list of {@link VirtualMachine} objects, each mirroring
336 * a target VM.
337 */
338 List<VirtualMachine> connectedVirtualMachines();
339
340 /**
341 * Returns the major version number of the JDI interface.
342 * See {@link VirtualMachine#version} target VM version and
343 * information and
344 * {@link VirtualMachine#description} more version information.
345 *
346 * @return the integer major version number.
347 */
348 int majorInterfaceVersion();
349
350 /**
351 * Returns the minor version number of the JDI interface.
352 * See {@link VirtualMachine#version} target VM version and
353 * information and
354 * {@link VirtualMachine#description} more version information.
355 *
356 * @return the integer minor version number
357 */
358 int minorInterfaceVersion();
359
360 /**
361 * Create a virtual machine mirror for a target VM.
362 *
363 * <p> Creates a virtual machine mirror for a target VM
364 * for which a {@link com.sun.jdi.connect.spi.Connection Connection}
365 * already exists. A Connection is created when a {@link
366 * com.sun.jdi.connect.Connector Connector} establishes
367 * a connection and successfully handshakes with a target VM.
368 * A Connector can then use this method to create a virtual machine
369 * mirror to represent the composite state of the target VM.
370 *
371 * <p> The <tt>process</tt> argument specifies the
372 * {@link java.lang.Process} object for the taget VM. It may be
373 * specified as <tt>null</tt>. If the target VM is launched
374 * by a {@link com.sun.jdi.connect.LaunchingConnector
375 * LaunchingConnector} the <tt>process</tt> argument should be
376 * specified, otherwise calling {@link com.sun.jdi.VirtualMachine#process()}
377 * on the created virtual machine will return <tt>null</tt>.
378 *
379 * <p> This method exists so that Connectors may create
380 * a virtual machine mirror when a connection is established
381 * to a target VM. Only developers creating new Connector
382 * implementations should need to make direct use of this
383 * method. </p>
384 *
385 * @param connection
386 * The open connection to the target VM.
387 *
388 * @param process
389 * If launched, the {@link java.lang.Process} object for
390 * the target VM. <tt>null</tt> if not launched.
391 *
392 * @return new virtual machine representing the target VM.
393 *
394 * @throws IOException
395 * if an I/O error occurs
396 *
397 * @throws IllegalStateException
398 * if the connection is not open
399 *
400 * @see com.sun.jdi.connect.spi.Connection#isOpen()
401 * @see com.sun.jdi.VirtualMachine#process()
402 *
403 * @since 1.5
404 */
405 VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException;
406
407 /**
408 * Creates a new virtual machine.
409 *
410 * <p> This convenience method works as if by invoking {@link
411 * #createVirtualMachine(Connection, Process)} method and
412 * specifying <tt>null</tt> as the <tt>process</tt> argument.
413 *
414 * <p> This method exists so that Connectors may create
415 * a virtual machine mirror when a connection is established
416 * to a target VM. Only developers creating new Connector
417 * implementations should need to make direct use of this
418 * method. </p>
419 *
420 * @return the new virtual machine
421 *
422 * @throws IOException
423 * if an I/O error occurs
424 *
425 * @throws IllegalStateException
426 * if the connection is not open
427 *
428 * @since 1.5
429 */
430 VirtualMachine createVirtualMachine(Connection connection) throws IOException;
431 }