| /* |
| * Copyright (c) 1998, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package com.sun.jdi; |
| |
| import com.sun.jdi.connect.*; |
| import com.sun.jdi.connect.spi.Connection; |
| import java.util.List; |
| import java.io.IOException; |
| |
| /** |
| * A manager of connections to target virtual machines. The |
| * VirtualMachineManager allows one application to debug |
| * multiple target VMs. (Note that the converse is not |
| * supported; a target VM can be debugged by only one |
| * debugger application.) This interface |
| * contains methods to manage connections |
| * to remote target VMs and to obtain the {@link VirtualMachine} |
| * mirror for available target VMs. |
| * <p> |
| * Connections can be made using one of several different |
| * {@link com.sun.jdi.connect.Connector} objects. Each connector encapsulates |
| * a different way of connecting the debugger with a target VM. |
| * <p> |
| * The VirtualMachineManager supports many different scenarios for |
| * connecting a debugger to a virtual machine. Four examples |
| * are presented in the table below. The |
| * examples use the command line syntax in Sun's implementation. |
| * Some {@link com.sun.jdi.connect.Connector} implementations may require slightly |
| * different handling than presented below. |
| * <p> |
| * <TABLE BORDER WIDTH="75%" SUMMARY="Four scenarios for connecting a debugger |
| * to a virtual machine"> |
| * <TR> |
| * <TH scope=col>Scenario</TH> |
| * <TH scope=col>Description</TH> |
| * <TR> |
| * <TD>Debugger launches target VM (simplest, most-common scenario)</TD> |
| * |
| * <TD>Debugger calls the |
| * {@link com.sun.jdi.connect.LaunchingConnector#launch(java.util.Map)} |
| * method of the default connector, obtained with {@link #defaultConnector}. The |
| * target VM is launched, and a connection between that VM and the |
| * debugger is established. A {@link VirtualMachine} mirror is returned. |
| * <P>Or, for more control |
| * <UL> |
| * <LI> |
| * Debugger selects a connector from the list returned by |
| * {@link #launchingConnectors} with desired characteristics |
| * (for example, transport type, etc.). |
| * <LI> |
| * Debugger calls the |
| * {@link com.sun.jdi.connect.LaunchingConnector#launch(java.util.Map)} |
| * method of the selected connector. The |
| * target VM is launched, and a connection between that VM and the |
| * debugger is established. A {@link VirtualMachine} mirror is returned. |
| * </UL> |
| * </TD> |
| * </TR> |
| * <TR> |
| * <TD>Debugger attaches to previously-running VM</TD> |
| * <TD> |
| * <UL> |
| * <LI> |
| * Target VM is launched using the options |
| * <code>-agentlib:jdwp=transport=xxx,server=y</code> |
| * </LI> |
| * <LI> |
| * Target VM generates and outputs the tranport-specific address at which it will |
| * listen for a connection.</LI> |
| * <LI> |
| * Debugger is launched. Debugger selects a connector in the list |
| * returned by {@link #attachingConnectors} matching the transport with |
| * the name "xxx". |
| * <LI> |
| * Debugger presents the default connector parameters (obtained through |
| * {@link com.sun.jdi.connect.Connector#defaultArguments()}) to the end user, |
| * allowing the user to |
| * fill in the transport-specific address generated by the target VM. |
| * <LI> |
| * Debugger calls the {@link com.sun.jdi.connect.AttachingConnector#attach(java.util.Map)} method |
| * of the selected to attach to the target VM. A {@link VirtualMachine} |
| * mirror is returned. |
| * </UL> |
| * </TD> |
| * </TR> |
| * |
| * <TR> |
| * <TD>Target VM attaches to previously-running debugger</TD> |
| * <TD> |
| * <LI> |
| * At startup, debugger selects one or more connectors from |
| * the list returned by {@link #listeningConnectors} for one or more |
| * transports.</LI> |
| * <LI> |
| * Debugger calls the {@link com.sun.jdi.connect.ListeningConnector#startListening(java.util.Map)} method for each selected |
| * connector. For each call, a transport-specific address string is |
| * generated and returned. The debugger makes the transport names and |
| * corresponding address strings available to the end user. |
| * <LI> |
| * Debugger calls |
| * {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} |
| * for each selected connector to wait for |
| * a target VM to connect.</LI> |
| * <LI> |
| * Later, target VM is launched by end user with the options |
| * <code>-agentlib:jdwp=transport=xxx,address=yyy</code> |
| * where "xxx" the transport for one of the connectors selected by the |
| * the debugger and "yyy" |
| * is the address generated by |
| * {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} for that |
| * transport.</LI> |
| * <LI> |
| * Debugger's call to {@link com.sun.jdi.connect.ListeningConnector#accept(java.util.Map)} returns |
| * a {@link VirtualMachine} mirror.</LI> |
| * </TD> |
| * </TR> |
| * |
| * <TR> |
| * <TD>Target VM launches debugger (sometimes called "Just-In-Time" debugging)</TD> |
| * <TD> |
| * <LI> |
| * Target VM is launched with the options |
| * <code>-agentlib:jdwp=launch=cmdline,onuncaught=y,transport=xxx,server=y</code> |
| * </LI> |
| * <LI> |
| * Later, an uncaught exception is thrown in the target VM. The target |
| * VM generates the tranport-specific address at which it will |
| * listen for a connection. |
| * <LI>Target VM launches the debugger with the following items concatenated |
| * together (separated by spaces) to form the command line: |
| * <UL> |
| * <LI> The launch= value |
| * <LI> The transport= value |
| * <LI> The generated transport-specific address at which VM is listening for |
| * debugger connection. |
| * </UL> |
| * <LI> |
| * Upon launch, debugger selects a connector in the list |
| * returned by {@link #attachingConnectors} matching the transport with |
| * the name "xxx". |
| * <LI> |
| * Debugger changes the default connector parameters (obtained through |
| * {@link com.sun.jdi.connect.Connector#defaultArguments()}) to specify |
| * the transport specific address at which the VM is listenig. Optionally, |
| * other connector arguments can be presented to the user. |
| * <LI> |
| * Debugger calls the |
| * {@link com.sun.jdi.connect.AttachingConnector#attach(java.util.Map)} method |
| * of the selected to attach to the target VM. A {@link VirtualMachine} |
| * mirror is returned. |
| * </TD> |
| * </TR> |
| * </TABLE> |
| * |
| * <p> Connectors are created at start-up time. That is, they |
| * are created the first time that {@link |
| * com.sun.jdi.Bootstrap#virtualMachineManager()} is invoked. |
| * The list of all Connectors created at start-up time can be |
| * obtained from the VirtualMachineManager by invoking the |
| * {@link #allConnectors allConnectors} method. |
| * |
| * <p> Connectors are created at start-up time if they are |
| * installed on the platform. In addition, Connectors are created |
| * automatically by the VirtualMachineManager to encapsulate any |
| * {@link com.sun.jdi.connect.spi.TransportService} implementations |
| * that are installed on the platform. These two mechanisms for |
| * creating Connectors are described here. |
| * |
| * <p> A Connector is installed on the platform if it is installed |
| * in a jar file that is visible to the defining class loader of |
| * the {@link com.sun.jdi.connect.Connector} type, |
| * and that jar file contains a provider configuration file named |
| * <tt>com.sun.jdi.connect.Connector</tt> in the resource directory |
| * <tt>META-INF/services</tt>, and the provider configuration file |
| * lists the full-qualified class name of the Connector |
| * implementation. A Connector is a class that implements the |
| * {@link com.sun.jdi.connect.Connector Connector} interface. More |
| * appropriately the class implements one of the specific Connector |
| * types, namely {@link com.sun.jdi.connect.AttachingConnector |
| * AttachingConnector}, {@link com.sun.jdi.connect.ListeningConnector |
| * ListeningConnector}, or {@link com.sun.jdi.connect.LaunchingConnector |
| * LaunchingConnector}. The format of the provider configuration file |
| * is one fully-qualified class name per line. Space and tab characters |
| * surrounding each class, as well as blank lines are ignored. The |
| * comment character is <tt>'#'</tt> (<tt>0x23</tt>), and on each |
| * line all characters following the first comment character are |
| * ignored. The file must be encoded in UTF-8. |
| * |
| * <p> At start-up time the VirtualMachineManager attempts to load |
| * and instantiate (using the no-arg constructor) each class listed |
| * in the provider configuration file. Exceptions thrown when loading |
| * or creating the Connector are caught and ignored. In other words, |
| * the start-up process continues despite of errors. |
| * |
| * <p> In addition to Connectors installed on the platform the |
| * VirtualMachineManager will also create Connectors to encapsulate |
| * any {@link com.sun.jdi.connect.spi.TransportService} implementations |
| * that are installed on the platform. A TransportService is |
| * installed on the platform if it installed in a jar file that is |
| * visible to the defining class loader for the |
| * {@link com.sun.jdi.connect.spi.TransportService} type, and that jar |
| * file contains a provider configuration file named |
| * <tt>com.sun.jdi.connect.spi.TransportService</tt> in the resource |
| * directory <tt>META-INF/services</tt>, and the provider |
| * configuration file lists the the full-qualified class name of the |
| * TransportService implementation. A TransportService is a concrete |
| * sub-class of {@link com.sun.jdi.connect.spi.TransportService |
| * TransportService}. The format of the provider configuration file |
| * is the same as the provider configuration file for Connectors |
| * except that each class listed must be the fully-qualified class |
| * name of a class that implements the TransportService interface. |
| * |
| * <p> For each TransportService installed on the platform, the |
| * VirtualMachineManager creates a corresponding |
| * {@link com.sun.jdi.connect.AttachingConnector} and |
| * {@link com.sun.jdi.connect.ListeningConnector}. These |
| * Connectors are created to encapsulate a {@link |
| * com.sun.jdi.connect.Transport Transport} that in turn |
| * encapsulates the TransportService. |
| * The AttachingConnector will be named based on the name of the |
| * transport service concatenated with the string <tt>Attach</tt>. |
| * For example, if the transport service {@link |
| * com.sun.jdi.connect.spi.TransportService#name() name()} method |
| * returns <tt>telepathic</tt> then the AttachingConnector will |
| * be named <tt>telepathicAttach</tt>. Similiarly the ListeningConnector |
| * will be named with the string <tt>Listen</tt> tagged onto the |
| * name of the transport service. The {@link |
| * com.sun.jdi.connect.Connector#description() description()} method |
| * of both the AttachingConnector, and the ListeningConnector, will |
| * delegate to the {@link com.sun.jdi.connect.spi.TransportService#description() |
| * description()} method of the underlying transport service. Both |
| * the AttachingConnector and the ListeningConnector will have two |
| * Connector {@link com.sun.jdi.connect.Connector$Argument Arguments}. |
| * A {@link com.sun.jdi.connect.Connector$StringArgument StringArgument} |
| * named <tt>address</tt> is the connector argument to specify the |
| * address to attach too, or to listen on. A |
| * {@link com.sun.jdi.connect.Connector$IntegerArgument IntegerArgument} |
| * named <tt>timeout</tt> is the connector argument to specify the |
| * timeout when attaching, or accepting. The timeout connector may be |
| * ignored depending on if the transport service supports an attach |
| * timeout or accept timeout. |
| * |
| * <p> Initialization of the virtual machine manager will fail, that is |
| * {@link com.sun.jdi.Bootstrap#virtualMachineManager()} will throw an |
| * error if the virtual machine manager is unable to create any |
| * connectors. |
| * |
| * @author Gordon Hirsch |
| * @since 1.3 |
| */ |
| @jdk.Exported |
| public interface VirtualMachineManager { |
| |
| /** |
| * Identifies the default connector. This connector should |
| * be used as the launching connector when selection of a |
| * connector with specific characteristics is unnecessary. |
| * |
| * @return the default {@link com.sun.jdi.connect.LaunchingConnector} |
| */ |
| LaunchingConnector defaultConnector(); |
| |
| /** |
| * Returns the list of known {@link com.sun.jdi.connect.LaunchingConnector} objects. |
| * Any of the returned objects can be used to launch a new target |
| * VM and immediately create a {@link VirtualMachine} mirror for it. |
| * |
| * Note that a target VM launched by a launching connector is not |
| * guaranteed to be stable until after the {@link com.sun.jdi.event.VMStartEvent} has been |
| * received. |
| * @return a list of {@link com.sun.jdi.connect.LaunchingConnector} objects. |
| */ |
| List<LaunchingConnector> launchingConnectors(); |
| |
| /** |
| * Returns the list of known {@link com.sun.jdi.connect.AttachingConnector} objects. |
| * Any of the returned objects can be used to attach to an existing target |
| * VM and create a {@link VirtualMachine} mirror for it. |
| * |
| * @return a list of {@link com.sun.jdi.connect.AttachingConnector} objects. |
| */ |
| List<AttachingConnector> attachingConnectors(); |
| |
| /** |
| * Returns the list of known {@link com.sun.jdi.connect.ListeningConnector} objects. |
| * Any of the returned objects can be used to listen for a |
| * connection initiated by a target VM |
| * and create a {@link VirtualMachine} mirror for it. |
| * |
| * @return a list of {@link com.sun.jdi.connect.ListeningConnector} objects. |
| */ |
| List<ListeningConnector> listeningConnectors(); |
| |
| /** |
| * Returns the list of all known {@link com.sun.jdi.connect.Connector} objects. |
| * |
| * @return a list of {@link com.sun.jdi.connect.Connector} objects. |
| */ |
| List<Connector> allConnectors(); |
| |
| /** |
| * Lists all target VMs which are connected to the debugger. |
| * The list includes {@link VirtualMachine} instances for |
| * any target VMs which initiated a connection |
| * and any |
| * target VMs to which this manager has initiated a connection. |
| * A target VM will remain in this list |
| * until the VM is disconnected. |
| * {@link com.sun.jdi.event.VMDisconnectEvent} is placed in the event queue |
| * after the VM is removed from the list. |
| * |
| * @return a list of {@link VirtualMachine} objects, each mirroring |
| * a target VM. |
| */ |
| List<VirtualMachine> connectedVirtualMachines(); |
| |
| /** |
| * Returns the major version number of the JDI interface. |
| * See {@link VirtualMachine#version} target VM version and |
| * information and |
| * {@link VirtualMachine#description} more version information. |
| * |
| * @return the integer major version number. |
| */ |
| int majorInterfaceVersion(); |
| |
| /** |
| * Returns the minor version number of the JDI interface. |
| * See {@link VirtualMachine#version} target VM version and |
| * information and |
| * {@link VirtualMachine#description} more version information. |
| * |
| * @return the integer minor version number |
| */ |
| int minorInterfaceVersion(); |
| |
| /** |
| * Create a virtual machine mirror for a target VM. |
| * |
| * <p> Creates a virtual machine mirror for a target VM |
| * for which a {@link com.sun.jdi.connect.spi.Connection Connection} |
| * already exists. A Connection is created when a {@link |
| * com.sun.jdi.connect.Connector Connector} establishes |
| * a connection and successfully handshakes with a target VM. |
| * A Connector can then use this method to create a virtual machine |
| * mirror to represent the composite state of the target VM. |
| * |
| * <p> The <tt>process</tt> argument specifies the |
| * {@link java.lang.Process} object for the taget VM. It may be |
| * specified as <tt>null</tt>. If the target VM is launched |
| * by a {@link com.sun.jdi.connect.LaunchingConnector |
| * LaunchingConnector} the <tt>process</tt> argument should be |
| * specified, otherwise calling {@link com.sun.jdi.VirtualMachine#process()} |
| * on the created virtual machine will return <tt>null</tt>. |
| * |
| * <p> This method exists so that Connectors may create |
| * a virtual machine mirror when a connection is established |
| * to a target VM. Only developers creating new Connector |
| * implementations should need to make direct use of this |
| * method. </p> |
| * |
| * @param connection |
| * The open connection to the target VM. |
| * |
| * @param process |
| * If launched, the {@link java.lang.Process} object for |
| * the target VM. <tt>null</tt> if not launched. |
| * |
| * @return new virtual machine representing the target VM. |
| * |
| * @throws IOException |
| * if an I/O error occurs |
| * |
| * @throws IllegalStateException |
| * if the connection is not open |
| * |
| * @see com.sun.jdi.connect.spi.Connection#isOpen() |
| * @see com.sun.jdi.VirtualMachine#process() |
| * |
| * @since 1.5 |
| */ |
| VirtualMachine createVirtualMachine(Connection connection, Process process) throws IOException; |
| |
| /** |
| * Creates a new virtual machine. |
| * |
| * <p> This convenience method works as if by invoking {@link |
| * #createVirtualMachine(Connection, Process)} method and |
| * specifying <tt>null</tt> as the <tt>process</tt> argument. |
| * |
| * <p> This method exists so that Connectors may create |
| * a virtual machine mirror when a connection is established |
| * to a target VM. Only developers creating new Connector |
| * implementations should need to make direct use of this |
| * method. </p> |
| * |
| * @return the new virtual machine |
| * |
| * @throws IOException |
| * if an I/O error occurs |
| * |
| * @throws IllegalStateException |
| * if the connection is not open |
| * |
| * @since 1.5 |
| */ |
| VirtualMachine createVirtualMachine(Connection connection) throws IOException; |
| } |
