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
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 }
|
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 *
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}
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 * <UL>
114 * <LI>
115 * At startup, debugger selects one or more connectors from
116 * the list returned by {@link #listeningConnectors} for one or more
117 * transports.</LI>
118 * <LI>
119 * Debugger calls the {@link com.sun.jdi.connect.ListeningConnector#startListening(java.util.Map)} method for each selected
120 * connector. For each call, a transport-specific address string is
121 * generated and returned. The debugger makes the transport names and
122 * corresponding address strings available to the end user.
123 * <LI>
124 * Debugger calls
125 * {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)}
126 * for each selected connector to wait for
127 * a target VM to connect.</LI>
128 * <LI>
129 * Later, target VM is launched by end user with the options
130 * {@code -agentlib:jdwp=transport=xxx,address=yyy}
131 * where "xxx" the transport for one of the connectors selected by the
132 * the debugger and "yyy"
133 * is the address generated by
134 * {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} for that
135 * transport.</LI>
136 * <LI>
137 * Debugger's call to {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} returns
138 * a {@link VirtualMachine} mirror.</LI>
139 * </UL>
140 * </TD>
141 * </TR>
142 *
143 * <TR>
144 * <TD>Target VM launches debugger (sometimes called "Just-In-Time" debugging)</TD>
145 * <TD>
146 * <UL>
147 * <LI>
148 * Target VM is launched with the options
149 * {@code -agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y}
150 * </LI>
151 * <LI>
152 * Later, an uncaught exception is thrown in the target VM. The target
153 * VM generates the tranport-specific address at which it will
154 * listen for a connection.
155 * <LI>Target VM launches the debugger with the following items concatenated
156 * together (separated by spaces) to form the command line:
157 * <UL>
158 * <LI> The launch= value
159 * <LI> The transport= value
160 * <LI> The generated transport-specific address at which VM is listening for
161 * debugger connection.
162 * </UL>
163 * <LI>
164 * Upon launch, debugger selects a connector in the list
165 * returned by {@link #attachingConnectors} matching the transport with
166 * the name "xxx".
167 * <LI>
168 * Debugger changes the default connector parameters (obtained through
169 * {@link com.sun.jdi.connect.Connector#defaultArguments()}) to specify
170 * the transport specific address at which the VM is listenig. Optionally,
171 * other connector arguments can be presented to the user.
172 * <LI>
173 * Debugger calls the
174 * {@link com.sun.jdi.connect.AttachingConnector#attach(java.util.Map)} method
175 * of the selected to attach to the target VM. A {@link VirtualMachine}
176 * mirror is returned.
177 * </UL>
178 * </TD>
179 * </TR>
180 * </TABLE>
181 *
182 * <p> Connectors are created at start-up time. That is, they
183 * are created the first time that {@link
184 * com.sun.jdi.Bootstrap#virtualMachineManager()} is invoked.
185 * The list of all Connectors created at start-up time can be
186 * obtained from the VirtualMachineManager by invoking the
187 * {@link #allConnectors allConnectors} method.
188 *
189 * <p> Connectors are created at start-up time if they are
190 * installed on the platform. In addition, Connectors are created
191 * automatically by the VirtualMachineManager to encapsulate any
192 * {@link com.sun.jdi.connect.spi.TransportService} implementations
193 * that are installed on the platform. These two mechanisms for
194 * creating Connectors are described here.
195 *
196 * <p> A Connector is installed on the platform if it is installed
197 * in a jar file that is visible to the defining class loader of
367 * <p> Creates a virtual machine mirror for a target VM
368 * for which a {@link com.sun.jdi.connect.spi.Connection Connection}
369 * already exists. A Connection is created when a {@link
370 * com.sun.jdi.connect.Connector Connector} establishes
371 * a connection and successfully handshakes with a target VM.
372 * A Connector can then use this method to create a virtual machine
373 * mirror to represent the composite state of the target VM.
374 *
375 * <p> The <tt>process</tt> argument specifies the
376 * {@link java.lang.Process} object for the taget VM. It may be
377 * specified as <tt>null</tt>. If the target VM is launched
378 * by a {@link com.sun.jdi.connect.LaunchingConnector
379 * LaunchingConnector} the <tt>process</tt> argument should be
380 * specified, otherwise calling {@link com.sun.jdi.VirtualMachine#process()}
381 * on the created virtual machine will return <tt>null</tt>.
382 *
383 * <p> This method exists so that Connectors may create
384 * a virtual machine mirror when a connection is established
385 * to a target VM. Only developers creating new Connector
386 * implementations should need to make direct use of this
387 * method.
388 *
389 * @param connection
390 * The open connection to the target VM.
391 *
392 * @param process
393 * If launched, the {@link java.lang.Process} object for
394 * the target VM. <tt>null</tt> if not launched.
395 *
396 * @return new virtual machine representing the target VM.
397 *
398 * @throws IOException
399 * if an I/O error occurs
400 *
401 * @throws IllegalStateException
402 * if the connection is not open
403 *
404 * @see com.sun.jdi.connect.spi.Connection#isOpen()
405 * @see com.sun.jdi.VirtualMachine#process()
406 *
407 * @since 1.5
408 */
409 VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException;
410
411 /**
412 * Creates a new virtual machine.
413 *
414 * <p> This convenience method works as if by invoking {@link
415 * #createVirtualMachine(Connection, Process)} method and
416 * specifying <tt>null</tt> as the <tt>process</tt> argument.
417 *
418 * <p> This method exists so that Connectors may create
419 * a virtual machine mirror when a connection is established
420 * to a target VM. Only developers creating new Connector
421 * implementations should need to make direct use of this
422 * method.
423 *
424 * @return the new virtual machine
425 *
426 * @throws IOException
427 * if an I/O error occurs
428 *
429 * @throws IllegalStateException
430 * if the connection is not open
431 *
432 * @since 1.5
433 */
434 VirtualMachine createVirtualMachine(Connection connection) throws IOException;
435 }
|