Documentation Contents

Java Platform Debugger Architecture
Java SE 1.5 Enhancements

The version 5.0 family of the JDK includes the following JPDA enhancements:


Addition of JVMTI

The Java Virtual Machine Tool Interface (JVMTI) is a new native programming interface for use by development and monitoring tools, which replaces JVMPI and JVMDI. It provides both a way to inspect the state and to control the execution of applications running in the Java virtual machine (VM). JVMTI is intended to provide a VM interface for the full breadth of tools that need access to VM state, including but not limited to: profiling, debugging, monitoring, thread analysis, and coverage analysis tools.

Note: JVMPI and JVMDI will be removed in the next major release of Java SE.


JPDA Now Supports Generics

Generics is a new feature in the Java programming langauge, and the JPDA interfaces now allow debuggers to access generic information. This change adds interface elements to the JDWP and JDI components of JPDA. These elements allow generic information to be accessed by JDI clients as Strings containing the actual contents of the Signature attributes from .class files.

JDWP changes

The following are new commands to JDWP. These are the similar to the previously-existing commands, but return generic signatures if they exist, in addition to the JNI signatures.

JDI changes

New methods:


JPDA Now Supports Enums

Enumeration types are a new feature in the Java programming langauge, and the JPDA interfaces now allow debuggers to access information about enumeration types.

New methods:


JPDA Now Supports Varargs

The ability to declare a method as accepting a variable number of agruments is a new feature in the Java programming langauge. The JDI now allows a debugger to query whether or not a method accepts a variable number of arguments. This change also modifies the three JDI methods that allow a method to be called to accept varargs.

New method in com.sun.jdi.Method:

Specification update for the following methods:


JPDA Pluggable Connections and Transports

The Java Debug Interface (JDI) previously lacked a provider interface to allow tool vendors to develop and deploy their own Connectors. A Connector is the means by which a Java debugger connects to a target virtual machine.

The JDK ships with 6 Connectors. Two of these are LaunchingConnectors, which are used to launch and establish a debugging session with a target VM. The other four Connectors encapsulate transports for remote debugging. The creation of these 6 Connectors was previously hardcoded into the Oracle JDI implementation of VirtualMachineManager and there was no means for tool vendors to develop or deploy additional Connectors.

Related to the above is that the Java Platform Debugger Architecture (JPDA) previously lacked a means for tool vendors to plug-in their own transport implementations. There was no supported way to debug over non-Oracle provided transports. The JDK ships with 2 transports - a TCP transport (for Solaris, Linux, and Windows) and a shared memory transport (Windows only).

There are two components to this enhancement:

  1. Extend the Java Debug Interface (JDI) with specification and a provider interface to allow 3rd party Connectors and Transport Services be developed and deployed
  2. Develop a VM/debuggee-side native interface to allow 3rd party transport libraries to be located and loaded by the debugging agent running in the VM

Specification updates for 5 existing classes/interfaces :

Two new methods added com.sun.jdi.VirtualMachineManager:

Four new classes :

Two new exceptions :

Native transport interface (defined by jdwpTransport.h)

New Connector arguments have been added as follows :

A "timeout" Connector argument has been added to the following Connectors (note that these are Connector names and not class names) :

The timeout argument is optional and specifies the attach or accept timeout (in milliseconds) to use when establishing a connection to the debuggee.

A "localAddress" Connector argument has been added to com.sun.jdi.SocketListen. This Connector argument specifies the local address to bind to when waiting to accept a connection from the debuggee.

Also, the options string to the JDWP agent has been amended to include a timeout option. The timeout argument specifies the timeout (in milliseconds) when establishing the connection to the debugger :

-agentlib:jdwp=...,...,timeout=<timeout>

In addition the address string for the dt_socket transport has been amended to take a local address when running in server mode. For example:

-agentlib:jdwp=transport=dt_socket,address=127.0.0.1:4000,server=y

indicates that the debugee bind to loopback address, port 4000 and wait for the debugger to connect.


JDWP Allow machine to be specified on address param for server

One of the JPDA options is the "address=" parameter, which has the format of:

JPDA Server: address=port

JPDA Client: address=machine:port

This change allows the server to accept a machine name, for cases where the JPDA server is running on a computer with more than one network card and address. The SunCommandLineLauncher, which is the default LaunchingConnector returned by Bootstrap.virtualMachineManager().defaultConnector(), now has a localAddress connector argument so that the local address can be specified. Also, the JDWP options string on the debugee-side can now accept a local address in addition to a port.


Read-only subset of JDI

When using JDI to debug a 'debuggee' that is unmodifiable (such as when the debuggee is represented by a corefile), the JDI client needs to know which JDI methods it can call and which it cannot. This change adds a method to the VirtualMachine interface that allows the JDI client to determine if that VM is read-only. It also defines various JDI methods as throwing a new exception if called on a read-only VM.

New method in com.sun.jdi.VirtualMachine.

New exception class:

The clause: @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. has been added to the specification of the following methods:

com.sun.jdi.ArrayReference

com.sun.jdi.ArrayType

com.sun.jdi.ClassType

com.sun.jdi.ObjectReference

com.sun.jdi.ClassType

com.sun.jdi.ObjectReference

com.sun.jdi.StackFrame

com.sun.jdi.ThreadGroupReference

com.sun.jdi.ThreadReference

com.sun.jdi.VirtualMachine


Tool to generate/analyze core files from a crashed JVM

When a JVM crashes, developers want to be able to look at a core file and understand what their code was doing when the crash occured. JDI, the Java Debug Interface, defines interfaces for 'connectors'. A connector is an implementation of one of these interfaces. Connectors are used to establish a connection between a debugger process and a debuggee. Java SE ships with several connectors that allow a debugger process to launch a debuggee, attach to an already running debuggee, or listen for incoming connections from a debuggee which has not yet run. These connectors are not part of the JDI specification but are part of the implementation of JDI on a platform. Other vendors are free to include whatever connectors they choose. In addition, users themselves can create their own connectors.

This feature adds three new connectors to the Oracle implementation. Each connector has a set of arguments that the JDI user can/must set in order to use the connector.

The interface summary below lists the class names of these three new connectors. This solution uses a Solaris private interface in libproc.h.

This will add three new attaching connectors to our release of Java SE:

These connectors will be contained in the list of connectors returned to a JDI client by the JDI methods:

These connectors are used by a JDI client in the same way that the other JDI attaching connectors are used.

The JDI VirtualMachine objects returned by these connectors' attach() methods are 'read-only'. This means that VirtualMachine.canBeModified() will return false. This in turn means that the methods defined in JDI as throwing VMCannotBeModifiedException if the VirtualMachine is read-only should not be called by the JDI client. These connectors can only be used to debug processes and corefiles that use the Oracle Hotspot Virtual Machine. These connectors are not available on Windows nor on Linux Itanium.


Need a way to timeout or test for connection with ListeningConnector.accept()

The method com.sun.jdi.connect.ListeningConnector.attach() previously waited indefinitely for a connection, with no way to set a timeout or interrupt the wait. This made it fairly dangerous to use in an integrated debugger. This change makes it possible to set a timeout, instantly test for a connection, or interrupt another thread.


Oracle and/or its affiliates Copyright © 1993, 2022, Oracle and/or its affiliates. All rights reserved.
Contact Us