Within JPDA the debugger application uses the Java Debug Interface (JDI) interface and the Connector abstraction to establish a connection to the target VM. The Connector used by the debugger application encapsulates the transport. On the target VM an agent supporting the Java Debug Wire Protocol is used to communicate with the debugger. This agent (which may be built into the target VM or loaded from a runtime library) encapsulates the transport to communicate with the debugger.
Two transport implementations are shipped with the reference implementation: A socket transport based on TCP/IP, and a shared memory transport. The specifications do not require any specific transport implementation to exist. In addition to transports provided with the implementation the architecture includes service provider interfaces to allow additional transports be developed and deployed.
Command and reply packets are written to the stream in accordance with the JDWP specification using the JDWP Transport Interface. Since many small packets can be sent over JDWP, the TCP_NO_DELAY socket option can improve performance in some socket implementations by avoiding delays that could occur if the socket implementation buffers small packets before sending them. Sockets are closed gracefully so that unsent data is sent if possible.
The socket transport is identified through a unique string, dt_socket. This name can be used to select the socket transport when invoking the target VM. Within the debugger application a corresponding Connector is used which encapsulates the socket transport.
In contexts where a client is attaching to a server, socket transport addresses have the format "<name>:<port>" where <name> is the host name and <port> is the socket port number at which it attaches or listens. In contexts where a server is waiting for a client to attach, the address consists of the port number alone (the host name is implicit).
The shared memory transport is identified through a unique string, dt_shmem. This name can be used to select the socket transport when invoking the target VM. Within the debugger application a corresponding Connector is used which encapsulates the shared memory transport.
Shared memory transport addresses are simply names that can be used as Microsoft Windows file-mapping object names. The name string can consist of any combination of characters, excluding the backslash.
A good JDI client application will allow users to choose and configure any connector that may be present, but it can be beneficial to incorporate knowledge of specific connectors into the debugger to make their configuration a more pleasant user experience. The example JDB implementation provided with the JPDA illustrates this approach.
The JDI reference implementations provides several connectors which map to the available transport types and the modes of connection (launching, listening, and attaching). These connectors are described in the following sections. A List containing these connectors is returned by JDI method VirtualMachineManager.allConnectors(). In addition, each attaching, listening, and launching connector is contained in the lists returned by the corresponding VirtualMachineManager methods attachingConnectors(), listeningConnectors(), and launchingConnectors().
This connector is uniquely identified by the name
"com.sun.jdi.CommandLineLaunch".
| name | required? | default value | description |
|---|---|---|---|
| home | no | current java.home property value | Location of the Java Runtime Environment (JRE) used to invoke the Target VM. |
| options | no | "" | Options, in addition to the standard debugging options, with which to invoke the VM. |
| main | yes | "" | The debugged application's main class and command line arguments. |
| suspend | no | true | True if the target VM is to be suspended immediately before the main class is loaded; false otherwise. |
| quote | yes | "\"" | The character used to combine space-delimited text on the command line. |
| vmexec | yes | "java" | The VM launcher executable. This can be changed to javaw or to java_g for debugging, if that launcher is available. |
This connector is uniquely identified by the name
"com.sun.jdi.RawCommandLineLaunch".
| name | required? | default value | description |
|---|---|---|---|
| command | yes | "" | Full command line to invoke the target VM with the application to be debugged.. |
| address | yes | "" | Transport address at which to listen for the newly launched target VM to connect. This value is typically part of the raw command argument as well, but this is not required if the target VM has some other means of determining the transport address to which it should connect. |
| quote | yes | "\"" | The character used to combine space-delimited text on the command line. |
This connector is uniquely identified by the name
"com.sun.jdi.SocketAttach".
| name | required? | default value | description |
|---|---|---|---|
| hostname | no | local host name | Name of host machine to connect to. |
| port | yes | "" | Port number on the host machine to connect to. |
| timeout | no | "" | The timeout, in milliseconds, to use when attaching to the target VM. |
This connector is uniquely identified by the name
"com.sun.jdi.SharedMemoryAttach".
| name | required? | default value | description |
|---|---|---|---|
| name | yes | "" | The shared memory transport address at which the target VM is listening.. |
| timeout | no | "" | The timeout, in milliseconds, to use when attaching to the target VM |
This connector can accept connections from multiple target VMs.
This connector is uniquely identified by the name
"com.sun.jdi.SocketListen".
| name | required? | default value | description |
|---|---|---|---|
| port | no | Ephemeral port number (port assigned by the TCP/IP stack) | Port number at which to listen for a connection.. |
| localAddress | no | All addresses assigned to the host | An IP address assigned to the host |
| timeout | no | "" | The timeout, in milliseconds, to use while waiting for the target VM to connect |
This connector can accept connections from multiple target VMs.
This connector is uniquely identified by the name
"com.sun.jdi.SharedMemoryListen".
| name | required? | default value | description |
|---|---|---|---|
| name | yes | "" | A shared memory transport address at which to listen for the target VM connection. |
| timeout | no | "" | The timeout, in milliseconds, to use while waiting for the target VM to connect |
| name | required? | default value | description |
|---|---|---|---|
| pid | yes | "" | The Process ID of a process to be debugged. |
| timeout | no | "" | The timeout, in milliseconds, to use when attaching to the target VM. |
| name | required? | default value | description |
|---|---|---|---|
| core |
no | core | Pathname of the core file to debug |
| javaExecutable |
yes |
"" |
Pathname of the Java executable that produced the core file. |
| name | required? | default value | description |
|---|---|---|---|
| pid | yes | "" | The Process ID of a process to be debugged. |
${JAVA_HOME}/bin/rmiregistry -J-Xbootclasspath/p:${JAVA_HOME}/lib/sa-jdi.jar
${JAVA_HOME}/bin/java \
-classpath ${JAVA_HOME}/lib/sa-jdi.jar \
sun.jvm.hotspot.jdi.SADebugServer \
<pid> \
[uniqueID]
or
${JAVA_HOME}/bin/java \
-classpath ${JAVA_HOME}/lib/sa-jdi.jar \
sun.jvm.hotspot.jdi.SADebugServer \
<pathname to the java executable that produced the core file>\
<pathname of the corefile to debug> \
[uniqueID]
An alternative to the above two steps is to use the jsadebugd (Solaris, Linux, or Mac OS X or Windows) command to start the RMI registry and debug-server on the remote machine.
'uniqueID' is an optional string. If more than one debug server is to run at the same time on the same machine, then each must have a different 'uniqueID' string.
In the above, JAVA_HOME must contain the pathname of a Java installation that is the same bit size (i.e. 32 bit/64 bit) and the same version (e.g. 5.0, 5.1) as the version used by the debuggee. However the debugger does not have to be the same bit size and version.
A process to be debugged need not have been started in debug mode(ie, with -agentlib:jdwp or -Xrunjdwp). It is permissable for the process to be hung. The process is suspended when the debug server attaches to it. When a debug server attached to a process is killed (by ^C or other means), the debuggee process will be resumed. Attaching more than one debug server to a corefile is permitted, but only one debug server can be attached to a process.
This connector allows multiple debugging sessions connected to the same debug server.
This connector is uniquely identified by the name "sun.jvm.hotspot.jdi.SADebugServerAttachingConnector".
| name | required? | default value | description |
|---|---|---|---|
| debugServerName | yes | "" | The IP address or name of the machine upon which the debug
server is running. If the machine contains multiple debug
servers, this name must be of the form uniqueID@IPAddress or uniqueID@hostname where 'uniqueID' is the string used to start the corresponding debug server. |
Oracle's VM implementation requires command line options to load the JDWP agent for debugging. The -agentlib:jdwp option is used to load and specify options to the JDWP agent.
The -agentlib:jdwp option is specified as follows:
-agentlib:jdwp=<name1>[=<value1>],<name2>[=<value2>]...
or
-Xrunjdwp:<name1>[=<value1>],<name2>[=<value2>]...
The following table describes the options that can be used:
| name | required? | default value | description |
|---|---|---|---|
| help | no | N/A | Prints a brief help message and exits the VM. |
| transport | yes | none | Name of the transport to use in connecting to debugger application. |
| server | no | "n" | If "y", listen for a debugger application to attach; otherwise,
attach to the debugger application at the specified
address.
If "y" and no address is specified, choose a transport address at which to listen for a debugger application, and print the address to the standard output stream. |
| address | yes, if server=n no, otherwise |
"" | Transport address for the connection. If server=n, attempt to attach to debugger application at this address. If server=y, listen for a connection at this address. |
| timeout | no | "" | If server=y specifies the timeout, in milliseconds, to wait for the debugger to attach. If server=n specifies the timeout, in milliseconds, to use when attaching to the debugger. Note that the timeout option may be ignored by some transport implementations. |
| launch | no | none | At completion of JDWP initialization, launch the process given
in this string. This option is used in combination with
onthrow and/or onuncaught to provide
"Just-In-Time debugging" in which a debugger process is launched
when a particular event occurs in this VM.
Note that the launched process is not started in its own window. In most cases the launched process should be a small application which in turns launches the debugger application in its own window. The following strings are appended to the string given in this argument (space-delimited). They can aid the launched debugger in establishing a connection with this VM. The resulting string is executed.
|
| onthrow | no | none | Delay initialization of the JDWP library until an exception of the given class is thrown in this VM. The exception class name must be package-qualified.Connection establishment is included in JDWP initialization, so it will not begin until the exception is thrown. |
| onuncaught | no | "n" | If "y", delay initialization of the JDWP library until an uncaught exception is thrown in this VM. Connection establishment is included in JDWP initialization, so it will not begin until the exception is thrown. See the JDI specification for com.sun.jdi.ExceptionEvent for a definition of uncaught exceptions. |
| suspend | no | "y" | If "y", VMStartEvent has a suspendPolicy of SUSPEND_ALL. If "n", VMStartEvent has a suspendPolicy of SUSPEND_NONE. |
JDI launching connectors cannot be used to debug Plug-in applets.
In JDB, the -attach option provides access to one of the attaching connectors in the reference implementation (shared memory on Microsoft Windows, sockets on the Solaris and Linux platforms). The -listen option provides access to one of the listening connectors in the reference implementation (shared memory on Microsoft Windows, sockets on the Solaris and Linux platforms). A class name and arguments specified directly on the command line provide access to the command line launching connector.
For example:
jdb -attach myhost:8000
is an easy way to attach to a target VM with the Socket Attaching Connector (on the Solaris operating environment), and
jdb Hello 1 2 3
is an easy way to launch a target VM with the Command Line Launching Connector.
However, the -connect option is also provided by JDB to handle any connector by taking an connector name and a set of arbitrary name/value argument pairs. For example the command lines above have the following equivalents.
jdb -connect
com.sun.jdi.SocketAttach:hostname=myhost,port=8000
jdb -connect "com.sun.jdi.CommandLineLaunch:main=Hello 1 2
3"
These command lines are more cumbersome than the ones above, but the -connect option can be used with any connector. This kind of operation is a primitive example of how a JDI debugger can deal with any kind of connector while providing a simplified interface for dealing with common, well-known connectors.
JPDA includes service provider interfaces to allow the development and deployment of connector and transport implementations. These service provider interfaces allow debugger and other tool vendors develop new connector implementations and provide addition transport mechanisms over and beyond the socket and shared memory transport provided by Oracle. The service provider interfaces in JDI are specified in the com.sun.jdi.connect.spi package.
In addition to the service provider interfaces in JDI the Oracle implementation also includes a transport library interface called the Java Debug Wire Protocol Transport Interface. A transport library is loaded by the JDWP agent in the target VM and is used to establish a connection to the debugger and to transport JDWP packets between the debugger and the VM.
Further information on the service provider interfaces can be in the document Java Platform Debugger Architecture - Service Provider Interfaces.
