/*
* Copyright (c) 1998, 2004, 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
*/
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;
}