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 }