View Javadoc
1   /*
2    * Copyright (c) 1998, 2013, 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.Exported
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 }