author | martin |
Thu, 30 Oct 2014 07:31:41 -0700 | |
changeset 28059 | e576535359cc |
parent 25859 | 3317bb8137f4 |
child 30037 | 3e785fad2c3b |
permissions | -rw-r--r-- |
2 | 1 |
/* |
23010
6dadb192ad81
8029235: Update copyright year to match last edit in jdk8 jdk repository for 2013
lana
parents:
20742
diff
changeset
|
2 |
* Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. |
2 | 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 |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 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 |
* |
|
5506 | 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. |
|
2 | 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 |
|
28059
e576535359cc
8067377: My hobby: caning, then then canning, the the can-can
martin
parents:
25859
diff
changeset
|
228 |
* configuration file lists the full-qualified class name of the |
2 | 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 |
*/ |
|
20742
4ae78e8060d6
8008662: Add @jdk.Exported to JDK-specific/exported APIs
alanb
parents:
5506
diff
changeset
|
274 |
@jdk.Exported |
2 | 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 |
} |