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 * 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 198 * the {@link com.sun.jdi.connect.Connector} type, 199 * and that jar file contains a provider configuration file named 200 * {@code com.sun.jdi.connect.Connector} in the resource directory 201 * {@code META-INF/services}, and the provider configuration file 202 * lists the full-qualified class name of the Connector 203 * implementation. A Connector is a class that implements the 204 * {@link com.sun.jdi.connect.Connector Connector} interface. More 205 * appropriately the class implements one of the specific Connector 206 * types, namely {@link com.sun.jdi.connect.AttachingConnector 207 * AttachingConnector}, {@link com.sun.jdi.connect.ListeningConnector 208 * ListeningConnector}, or {@link com.sun.jdi.connect.LaunchingConnector 209 * LaunchingConnector}. The format of the provider configuration file 210 * is one fully-qualified class name per line. Space and tab characters 211 * surrounding each class, as well as blank lines are ignored. The 212 * comment character is {@code '#'} ({@code 0x23}), and on each 213 * line all characters following the first comment character are 214 * ignored. The file must be encoded in UTF-8. 215 * 216 * <p> At start-up time the VirtualMachineManager attempts to load 217 * and instantiate (using the no-arg constructor) each class listed 218 * in the provider configuration file. Exceptions thrown when loading 219 * or creating the Connector are caught and ignored. In other words, 220 * the start-up process continues despite of errors. 221 * 222 * <p> In addition to Connectors installed on the platform the 223 * VirtualMachineManager will also create Connectors to encapsulate 224 * any {@link com.sun.jdi.connect.spi.TransportService} implementations 225 * that are installed on the platform. A TransportService is 226 * installed on the platform if it installed in a jar file that is 227 * visible to the defining class loader for the 228 * {@link com.sun.jdi.connect.spi.TransportService} type, and that jar 229 * file contains a provider configuration file named 230 * {@code com.sun.jdi.connect.spi.TransportService} in the resource 231 * directory {@code META-INF/services}, and the provider 232 * configuration file lists the full-qualified class name of the 233 * TransportService implementation. A TransportService is a concrete 234 * sub-class of {@link com.sun.jdi.connect.spi.TransportService 235 * TransportService}. The format of the provider configuration file 236 * is the same as the provider configuration file for Connectors 237 * except that each class listed must be the fully-qualified class 238 * name of a class that implements the TransportService interface. 239 * 240 * <p> For each TransportService installed on the platform, the 241 * VirtualMachineManager creates a corresponding 242 * {@link com.sun.jdi.connect.AttachingConnector} and 243 * {@link com.sun.jdi.connect.ListeningConnector}. These 244 * Connectors are created to encapsulate a {@link 245 * com.sun.jdi.connect.Transport Transport} that in turn 246 * encapsulates the TransportService. 247 * The AttachingConnector will be named based on the name of the 248 * transport service concatenated with the string {@code Attach}. 249 * For example, if the transport service {@link 250 * com.sun.jdi.connect.spi.TransportService#name() name()} method 251 * returns {@code telepathic} then the AttachingConnector will 252 * be named {@code telepathicAttach}. Similiarly the ListeningConnector 253 * will be named with the string {@code Listen} tagged onto the 254 * name of the transport service. The {@link 255 * com.sun.jdi.connect.Connector#description() description()} method 256 * of both the AttachingConnector, and the ListeningConnector, will 257 * delegate to the {@link com.sun.jdi.connect.spi.TransportService#description() 258 * description()} method of the underlying transport service. Both 259 * the AttachingConnector and the ListeningConnector will have two 260 * Connector {@link com.sun.jdi.connect.Connector.Argument Arguments}. 261 * A {@link com.sun.jdi.connect.Connector.StringArgument StringArgument} 262 * named {@code address} is the connector argument to specify the 263 * address to attach too, or to listen on. A 264 * {@link com.sun.jdi.connect.Connector.IntegerArgument IntegerArgument} 265 * named {@code timeout} is the connector argument to specify the 266 * timeout when attaching, or accepting. The timeout connector may be 267 * ignored depending on if the transport service supports an attach 268 * timeout or accept timeout. 269 * 270 * <p> Initialization of the virtual machine manager will fail, that is 271 * {@link com.sun.jdi.Bootstrap#virtualMachineManager()} will throw an 272 * error if the virtual machine manager is unable to create any 273 * connectors. 274 * 275 * @author Gordon Hirsch 276 * @since 1.3 277 */ 278 public interface VirtualMachineManager { 279 280 /** 281 * Identifies the default connector. This connector should 282 * be used as the launching connector when selection of a 283 * connector with specific characteristics is unnecessary. 284 * 285 * @return the default {@link com.sun.jdi.connect.LaunchingConnector} 286 */ 287 LaunchingConnector defaultConnector(); 288 289 /** 290 * Returns the list of known {@link com.sun.jdi.connect.LaunchingConnector} objects. 291 * Any of the returned objects can be used to launch a new target 292 * VM and immediately create a {@link VirtualMachine} mirror for it. 293 * 294 * Note that a target VM launched by a launching connector is not 295 * guaranteed to be stable until after the {@link com.sun.jdi.event.VMStartEvent} has been 296 * received. 297 * @return a list of {@link com.sun.jdi.connect.LaunchingConnector} objects. 298 */ 299 List<LaunchingConnector> launchingConnectors(); 300 301 /** 302 * Returns the list of known {@link com.sun.jdi.connect.AttachingConnector} objects. 303 * Any of the returned objects can be used to attach to an existing target 304 * VM and create a {@link VirtualMachine} mirror for it. 305 * 306 * @return a list of {@link com.sun.jdi.connect.AttachingConnector} objects. 307 */ 308 List<AttachingConnector> attachingConnectors(); 309 310 /** 311 * Returns the list of known {@link com.sun.jdi.connect.ListeningConnector} objects. 312 * Any of the returned objects can be used to listen for a 313 * connection initiated by a target VM 314 * and create a {@link VirtualMachine} mirror for it. 315 * 316 * @return a list of {@link com.sun.jdi.connect.ListeningConnector} objects. 317 */ 318 List<ListeningConnector> listeningConnectors(); 319 320 /** 321 * Returns the list of all known {@link com.sun.jdi.connect.Connector} objects. 322 * 323 * @return a list of {@link com.sun.jdi.connect.Connector} objects. 324 */ 325 List<Connector> allConnectors(); 326 327 /** 328 * Lists all target VMs which are connected to the debugger. 329 * The list includes {@link VirtualMachine} instances for 330 * any target VMs which initiated a connection 331 * and any 332 * target VMs to which this manager has initiated a connection. 333 * A target VM will remain in this list 334 * until the VM is disconnected. 335 * {@link com.sun.jdi.event.VMDisconnectEvent} is placed in the event queue 336 * after the VM is removed from the list. 337 * 338 * @return a list of {@link VirtualMachine} objects, each mirroring 339 * a target VM. 340 */ 341 List<VirtualMachine> connectedVirtualMachines(); 342 343 /** 344 * Returns the major version number of the JDI interface. 345 * See {@link VirtualMachine#version} target VM version and 346 * information and 347 * {@link VirtualMachine#description} more version information. 348 * 349 * @return the integer major version number. 350 */ 351 int majorInterfaceVersion(); 352 353 /** 354 * Returns the minor version number of the JDI interface. 355 * See {@link VirtualMachine#version} target VM version and 356 * information and 357 * {@link VirtualMachine#description} more version information. 358 * 359 * @return the integer minor version number 360 */ 361 int minorInterfaceVersion(); 362 363 /** 364 * Create a virtual machine mirror for a target VM. 365 * 366 * <p> Creates a virtual machine mirror for a target VM 367 * for which a {@link com.sun.jdi.connect.spi.Connection Connection} 368 * already exists. A Connection is created when a {@link 369 * com.sun.jdi.connect.Connector Connector} establishes 370 * a connection and successfully handshakes with a target VM. 371 * A Connector can then use this method to create a virtual machine 372 * mirror to represent the composite state of the target VM. 373 * 374 * <p> The {@code process} argument specifies the 375 * {@link java.lang.Process} object for the taget VM. It may be 376 * specified as {@code null}. If the target VM is launched 377 * by a {@link com.sun.jdi.connect.LaunchingConnector 378 * LaunchingConnector} the {@code process} argument should be 379 * specified, otherwise calling {@link com.sun.jdi.VirtualMachine#process()} 380 * on the created virtual machine will return {@code null}. 381 * 382 * <p> This method exists so that Connectors may create 383 * a virtual machine mirror when a connection is established 384 * to a target VM. Only developers creating new Connector 385 * implementations should need to make direct use of this 386 * method. 387 * 388 * @param connection 389 * The open connection to the target VM. 390 * 391 * @param process 392 * If launched, the {@link java.lang.Process} object for 393 * the target VM. {@code null} if not launched. 394 * 395 * @return new virtual machine representing the target VM. 396 * 397 * @throws IOException 398 * if an I/O error occurs 399 * 400 * @throws IllegalStateException 401 * if the connection is not open 402 * 403 * @see com.sun.jdi.connect.spi.Connection#isOpen() 404 * @see com.sun.jdi.VirtualMachine#process() 405 * 406 * @since 1.5 407 */ 408 VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException; 409 410 /** 411 * Creates a new virtual machine. 412 * 413 * <p> This convenience method works as if by invoking {@link 414 * #createVirtualMachine(Connection, Process)} method and 415 * specifying {@code null} as the {@code process} argument. 416 * 417 * <p> This method exists so that Connectors may create 418 * a virtual machine mirror when a connection is established 419 * to a target VM. Only developers creating new Connector 420 * implementations should need to make direct use of this 421 * method. 422 * 423 * @return the new virtual machine 424 * 425 * @throws IOException 426 * if an I/O error occurs 427 * 428 * @throws IllegalStateException 429 * if the connection is not open 430 * 431 * @since 1.5 432 */ 433 VirtualMachine createVirtualMachine(Connection connection) throws IOException; 434 }