Documentation Contents

# Java Platform Debugger Architecture
Java SE 1.4 Enhancements

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

- Full Speed Debugging
- Enable "HotSwap" Class File Replacement
- Instance Filters
- Support For Debugging Other Languages
- VMDeathRequests

## Full Speed Debugging

The Java HotSpot virtual machine now uses "full-speed debugging". In the previous version of HotSpot, when debugging was enabled, the program executed using only the interpreter. Now, the full performance advantage of HotSpot Technology is available to programs running with debugging enabled. The improved performance allows long running programs to be more easily debugged. It also allows testing to proceed at full speed and the launch of a debugger to occur on an exception:

            -Xrunjdwp:transport=dt_socket,server=y,onuncaught=y,launch=myDebuggerLaunchScript

For details on launch "onthrow" and launch "onuncaught", see Connection and Invocation Details. Setting a breakpoint only inhibits compilation (full speed execution) for the method containing the breakpoint. Execution reverts to the interpreter during some debug operations such as single-stepping and when method entry/exit or watchpoints are set.

As of version 1.4.1, full-speed debugging is available with both the Java HotSpot Client VM (default) and Java HotSpot Server VM (invoked with the `-server` command-line flag). In the JDK 1.4.0, full-speed debugging was available only with the Java HotSpot Client VM.

## Enable "HotSwap" Class File Replacement

This new feature encapsulates the ability to substitute modified code in a running application through the debugger APIs. For example, one can recompile a single class and replace the old instance with the new instance.

This change was made to address these issues:

- Tool (IDE) vendors want the ability to do fix-and-continue debugging. That is, while debugging, identify a problem, fix it, and continue debugging with fixed code.
- Organizations deploying long running servers wish to be able to fix bugs without taking down the server.

HotSwap adds functionality to the Java Platform Debugger Architecture (JPDA) to allow a class to be updated while under the control of a debugger. The two central components of this functionality are `RedefineClasses` which replaces the class definitions and `PopFrame` which pops frames off the stack allowing a method which has been redefined to be re-executed.

In the reference implementation, this functionality is implemented at the Java Virtual Machine Debug Interface (JVMDI) layer and made available through the higher layers of JPDA - the Java Debug Wire Protocol (JDWP) and the Java Debug Interface (JDI).

Redefinition Functionality
JDI | `VirtualMachine.redefineClasses(Map classToBytes)`
JDWP | `RedefineClasses (Cmd 18) in VirtualMachine (CmdSet 1)`
JVMDI | `RedefineClasses(jint classCount, JVMDI_class_definition *classDefs)`

Pop Frame Functionality
JDI | `ThreadReference.popFrames(StackFrame frame)`
JDWP | `PopFrames (Cmd 4) in StackFrame (CmdSet 16)`
JVMDI | `PopFrame(jthread thread)`

All functionality at each layer is independently optional. The `GetCapabilities` function at the JVMDI layer; the `CapabilitiesNew` command at the JDWP layer; and the `canRedefineClasses`, `canAddMethod`, `canUnrestrictedlyRedefineClasses`, and `canPopFrames`, methods at the JDI layer describe what functionality is implemented.

The bug report associated with this change is 4287595.

## Instance Filters

`BreakpointRequest`, `MethodExitRequest`, `ExceptionRequest`, `StepRequest`, `WatchpointRequest` and `MethodEntryRequest` classes now have the capability of adding instance filters by using the `addInstanceFilter` method. Instance filters restrict the events generated by a request to those in which the currently executing instance is the object specified.

## Support For Debugging Other Languages

The Java Platform Debugger Architecture has been extended so that non-Java programming language source, which is translated to Java programming language source, can be debugged in the future. The table below describes the new APIs and APIs with comments that have changed. This information is based on the SourceDebugExtension.

Package | New APIs | APIs with Changed Comments
--- | --- | ---
JVMDI | `GetSourceDebugExtension` | ``
JDWP - `ReferenceType` (2) Command Set | `SourceDebugExtension` Command (12) | ``
JDWP - `VirtualMachine` (1) Command Set | `SetDefaultStratum` Command (19) | ``
JDK - `VirtualMachine` I/F | `void setDefaultStratum(String stratum)` | ``
JDK - `VirtualMachine` I/F | `String getDefaultStratum()` | ``
JDI - `ReferenceType` I/F | `String sourceNames(String stratum)` | `String sourceName()`
JDI - `ReferenceType` I/F | `String sourcePaths(String stratum)` |
JDI - `ReferenceType` I/F | `List allLineLocations(String stratum, String sourceName)` | `List allLineLocations()`
JDI - `ReferenceType` I/F | `List locationsOfLine(String stratum, String sourceName, int lineNumber)` | `List locationsOfLine(int lineNumber)`
JDI - `ReferenceType` I/F | `List availableStrata()` | ``
JDI - `ReferenceType` I/F | `String defaultStratum()` | ``
JDI - `ReferenceType` I/F | `String sourceDebugExtension()` | ``
JDK - `Method` I/F | `List allLineLocations(String stratum, String sourceName)` | `List allLineLocations()`
JDK - `Method` I/F | `List locationsOfLine(String stratum, String sourceName, int lineNumber)` | `List locationsOfLine(int lineNumber)`
JDI - `Location` I/F | `` | class comment (strata defined)
JDI - `Location` I/F | `int lineNumber(String stratum)` | `int lineNumber()`
JDI - `Location` I/F | `String sourceName(String stratum)` | `String sourceName()`
JDI - `Location` I/F | `String sourcePath(String stratum)` | ``
JDI - `Location` I/F | `String sourcePath()` | ``

## VMDeathRequests

Using class `VMDeathRequest`, a request can be made for notification when the target VM terminates. When an enabled `VMDeathRequest` is satisfied, an `EventSet` containing a `VMDeathEvent` will be placed on the `EventQueue`.

Even without creating a `VMDeathRequest`, a single unsolicited `VMDeathEvent` will be sent with a `suspend policy` of `SUSPEND_NONE`.

This request would typically be created so that a `VMDeathEvent` with a suspend policy of `SUSPEND_ALL` will be sent. This event can be used to assure completion of any processing which requires the VM to be alive (e.g. event processing). Note: the unsolicited `VMDeathEvent` will still be sent.

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