Documentation Contents

Connection and Invocation Details                         

Contents

Transports

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.

Socket Transport

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).

Shared Memory Transport

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.

Connectors

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().

Command Line Launching Connector

This connector is uniquely identified by the name "com.sun.jdi.CommandLineLaunch".
 

Raw Command Line Launching Connector

This connector is uniquely identified by the name "com.sun.jdi.RawCommandLineLaunch".
 

Socket Attaching Connector

This connector is uniquely identified by the name "com.sun.jdi.SocketAttach".
 

Shared Memory Attaching Connector

This connector is uniquely identified by the name "com.sun.jdi.SharedMemoryAttach".
 

Socket Listening Connector

This connector can accept connections from multiple target VMs.

This connector is uniquely identified by the name "com.sun.jdi.SocketListen".
 

Shared Memory Listening Connector

This connector can accept connections from multiple target VMs.

This connector is uniquely identified by the name "com.sun.jdi.SharedMemoryListen".
 

Process Attaching Connector

SA Core Attaching Connector

        
${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]

${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]

Oracle VM Invocation Options

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=<sub-options>

Loads the JPDA reference implementation of JDWP. This library resides in the target VM and uses JVM TI 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 in -Xrunjdwp Sub-options.

-agentlib:jdwp and -Xrunjdwp sub-options

    -agentlib:jdwp=<name1>[=<value1>],<name2>[=<value2>]...

or

    -Xrunjdwp:<name1>[=<value1>],<name2>[=<value2>]...

The following table describes the options that can be used:

Examples

-agentlib:jdwp=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.

-agentlib:jdwp=transport=dt_socket,server=y,address=localhost:8000,timeout=5000

Listen for a socket connection on port 8000 on the loopback address only. Terminate if the debugger does not attach within 5 seconds. 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.

-agentlib:jdwp=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.

-agentlib:jdwp=transport=dt_socket,address=myhost:8000

Attach to a running debugger application via socket on host myhost at port 8000. Suspend this VM before the main class loads.

-agentlib:jdwp=transport=dt_shmem,address=mysharedmemory

Attach to a running debugger application via shared memory at transport address "mysharedmemory". Suspend this VM before the main class loads.

-agentlib:jdwp=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.

-agentlib:jdwp=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

JDI launching connectors cannot be used to debug Plug-in applets.

Connecting with JDB

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.

Service Provider Interfaces

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.

---

Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved.

Contact Us