|
Connection and Invocation Details
|
Contents
Transports
Connectors
Sun VM Invocation Options
Debugging Plug-in Applets
Connecting with JDB
Transports
A JPDA transport is a form of inter-process communication used by
a debugger application process and the virtual machine that is being debugged
(often called the target VM). JDI and JDWP admit the existence of
transports and refer to individual transports by a unique name, but the
JDI and JDWP specifications do not require specific transport implementations
to exist. Transport implementations can allow communications between processes
running in a single machine, on different machines, or either.
In establishing a connection between a debugger application and a target
VM, one side acts as a server, listening for a connection. At some later
time the other side attaches to the listener and a connection is established.
JPDA transports allow either the debugger application or the target VM
to act as a server. During the establishment of a connection, transport
addresses are used to identify the other side of a connection. Transport
addresses are strings; their format depends on the transport implementation.
The JPDA reference implementation on Win32 provides two transports:
a shared memory transport and a socket transport. The JPDA reference implementation
on Solaris platforms provides a socket transport. Future versions of the
JPDA reference implementation may include additional transports, Future
versions of the JPDA specification may provide an interface for plugging
additional transports into an implementation.
Socket Transport
The JPDA reference implementation provides a socket transport on both Solaris
and Win32 platforms. The socket transport uses standard TCP/IP sockets
to communicate information between debugger applications and target VM.
With the socket transport, the debugger application and target VM can reside
either on the same machine or on different machines. 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 and when selecting a JDI connector.
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).
Shared Memory Transport
In addition to the socket transport, the JPDA reference implementation
provides a shared memory transport on the Win32 platform. The shared transport
uses Win32 shared memory primitives to communicate information between
debugger applications and target VM. With the shared memory transport,
the debugger application and target VM must reside on the same machine.
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 and when selecting a JDI connector.
Shared memory transport addresses are simply names that can be used
as Win32 file-mapping object names.The name string can consist of any combination
of characters, excluding the backslash.
Connectors
A connector is a JDI abstraction that is used in establishing a
connection between a debugger application (written to the JDI) and a target
VM. Different JDI implementations are free to provide different connector
implementations to match the transports and VMs they support. The connector
interfaces are very general, to allow JDI to be used with varying connector
implementations. Connectors are configured through a set of name/value
pairs. Specific connectors accept different name/value pairs.
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.
Sun Command Line Launching Connector
This connector can be used by a debugger application to launch a Sun VM
or any other VM which supports the same invocation options
with respect to debugging. The details of launching the VM and specifying
the necessary debug options are handled by the connector. The underlying
transport used by this connector depends on the platform. On Win32, the
shared memory transport is used. On Solaris, the socket transport is used.
This connector is uniquely identified by the name "com.sun.jdi.CommandLineLaunch".
Sun Command Line Launching Connector Arguments
| name |
required? |
default value |
description |
| home |
no |
current java.home property value |
Location of the Java 2 Runtime Environment 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. |
Raw Command Line Launching Connector
This connector can be used by a debugger application to launch any VM.
The entire command line must be specified and it is not edited in any way.
The details of launching the VM with the given command line are handled
by the connector. The underlying transport used by this connector depends
on the platform. On Win32, the shared memory transport is used. On Solaris,
the socket transport is used.
This connector is uniquely identified by the name "com.sun.jdi.RawCommandLineLaunch".
Raw Command Line Launching Connector Arguments
| 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. |
Socket Attaching Connector
This connector can be used by a debugger application to attach to a currently
running target VM through the socket transport.. The target VM must have
been invoked with options consistent with this connector's arguments described
in the table below. For Sun VMs, the necessary options are described below.
This connector is uniquely identified by the name "com.sun.jdi.SocketAttach".
Socket Attaching Connector Arguments
| 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. |
Shared Memory Attaching Connector
This connector can be used by a debugger application to attach to a currently
running target VM through the shared memory transport..It is available
only on the Win32 platform. The target VM must have been invoked with options
consistent with this connectors arguments described in the table below.
For Sun VMs, the necessary options are described below.
This connector is uniquely identified by the name "com.sun.jdi.SharedMemoryAttach".
Shared Memory Attaching Connector Arguments
| name |
required? |
default value |
description |
| name |
yes |
"" |
The shared memory transport address at which
the target VM is listening.. |
Socket Listening Connector
This connector can be used by a debugger application to accept a connection
from a separately invoked target VM through the socket transport.. The
target VM must be invoked with options consistent with this connector's
arguments described in the table below. For Sun VMs, the necessary options
are described below.
This connector can accept connections from multiple target VMs.
This connector is uniquely identified by the name "com.sun.jdi.SocketListen".
Socket Listening Connector Arguments
| name |
required? |
default value |
description |
| port |
yes |
"" |
Port number at which to listen for a connection.. |
Shared Memory Listening Connector
This connector can be used by a debugger application to accept a connection
from a separately invoked target VM through the shared memory transport..It
is available only on the Win32 platform. The target VM must be invoked
with options consistent with this connectors arguments described in the
table below. For Sun VMs, the necessary options are described below.
This connector can accept connections from multiple target VMs.
This connector is uniquely identified by the name "com.sun.jdi.SharedMemoryListen".
Shared Memory Listening Connector Arguments
| name |
required? |
default value |
description |
| name |
yes |
"" |
A shared memory transport address at which
to listen for the target VM connection. |
Sun VM Invocation Options
This section describes the options necessary to invoke Sun VMs for debugging.
If your debugger application uses the JDI Sun Command
Line Launching Connector, the appropriate options are set for you.
In other cases, when the VM is invoked manually, you will need to set them.
Required Classic VM Options
The following VM invocation options are required to debug applications
running under the classic VM.
-
-Xdebug
-
Enables debugging
-
-Xnoagent
-
Disables the old sun.tools.debug agent. JPDA attaches its "agent"
in a different manner, described below.
-
-Djava.compiler=NONE
-
Disables the JIT compiler. Debugging with the classic VM requires that
it's JIT compiler be disabled.
-
-Xrunjdwp:<sub-options>
-
Loads the JPDA reference implementation of JDWP. This library resides in
the target VM and uses JVMDI and JNI to interact with it. It uses a transport
and the JDWP protocol to communicate with a separate debugger application.
Specific sub-options are described below.
If the Hotspot Performance Engine is installed, the -classic
is
necessary to select the classic VM.
Required Hotspot Performance Engine Options
The Hotspot Performance Engine requires the -Xdebug and -Xrunjdwp
options described above. The -Xnoagent and -Djava.compiler=NONE
options are not required; however, for compatibility, these options are
accepted and ignored.
-Xrunjdwp sub-options
The -Xrunjdwp option can be further qualified with sub-options. The sub-options
are specified as follows:
-Xrunjdwp:<name1>[=<value1>],<name2>[=<value2>]...
The table below describes the options that can be used:
-Xrunjdwp Sub-options
| 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. |
| 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.
-
The value of the transport sub-option.
-
The value of the address sub-option (or the generated address
if one is not given)
|
| 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. |
| stdalloc |
no |
"n" |
By default, the JDWP reference implementation uses an alternate allocator
for its memory allocation. If "y", the standard C runtime library allocator
will be used. This option is mainly for testing; use it with care. Deadlocks
can occur in this VM if the alternative allocator is disabled. |
| strict |
no |
"n" |
If "y", assume strict JVMDI conformance. This will disable all workarounds
to known bugs in JVMDI implementations. This option is mainly for testing
and should be used with care. |
| suspend |
no |
"y" |
If "y", VMStartEvent has a suspendPolicy of SUSPEND_ALL.
If "n", VMStartEvent has a suspendPolicy of SUSPEND_NONE. |
-Xrunjdwp Examples
-
-Xrunjdwp:transport=dt_socket,server=y,address=8000
-
Listen for a socket connection on port 8000. Suspend this VM before main
class loads (suspend=y by default). Once the debugger application connects,
it can send a JDWP command to resume the VM.
-
-
-Xrunjdwp:transport=dt_shmem,server=y,suspend=n
-
Choose an available shared memory transport address and print it to stdout.
Listen for a shared memory connection at that address. Allow the VM to
begin executing before the debugger application attaches.
-
-
-Xrunjdwp:transport=dt_socket,address=myhost:8000
-
Attach to a running debugger application via socket on host myhost at port
8000. Suspend this VM before main class loads.
-
-
-Xrunjdwp:transport=dt_shmem,address=mysharedmemory
-
Attach to a running debugger application via shared memory at transport
address "mysharedmemory". Suspend this VM before main class loads.
-
-
-Xrunjdwp:transport=dt_socket,server=y,address=8000,onthrow=java.io.IOException,launch=/usr/local/bin/debugstub
-
Wait for an instance of java.io.IOException to be thrown in this VM. Suspend
the VM (suspend=y by default). Listen for a socket connection on port 8000.
Execute the following: "/usr/local/bin/debugstub dt_socket myhost:8000".
This program can launch a debugger process in a separate window which
will attach to this VM and begin debugging it.
-
-
-Xrunjdwp:transport=dt_shmem,server=y,onuncaught=y,launch=d:\bin\debugstub.exe
-
Wait for an uncaught exception to be thrown in this VM. Suspend the VM.
Select a shared memory transport address and listen for a connection at
that address. Execute the following: "d:\bin\debugstub.exe dt_shmem
<address>", where <address> is the selected shared
memory address. This program can launch a debugger process in
a separate window which will attach to this VM and begin debugging it.
-
-
Debugging Plug-in Applets
Beginning with version 1.2.2 of the Java Plug-in, applets running under
the Plug-in can be debugged. The required VM options described above
can be specified in the Plug-In control panel, under the "Basic" tab, in
the "Java Run-Time Parameters". The debug options under the "Advanced"
tab should not be used as they will enable the old sun.tools.debug
debug
support. In future versions of the Plug-in, these debug options will be
changed to use JPDA.
JDI launching connectors cannot be used to
debug Plug-in applets.
Connecting with JDB
The example implementation of JDB provided with the JPDA, provides an illustration
of the usage of JDI connectors. There are "shortcut" options to JDB which
assume the use of connectors known to it (that is, connectors present in
the reference implementation). It also provides a way to establish a general
connection using any connector. While JDB is hardly an example of a good
debugger interface, it does provide a simple example of connectors in use.
In JDB, the -attach option provides access to one of the attaching connectors
in the reference implementation (shared memory on Win32, sockets on Solaris).
The -listen option provides access to one of the listening connectors in
the reference implementation (shared memory on Win32, sockets on Solaris).
A class name and arguments specified directly on the command line provide
access to the Sun 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 Solaris), and
jdb Hello 1 2 3
is an easy way to launch a target VM with the Sun 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.
