Skip navigation links

Introduction

This document lists changes made to the Debugger JPDA APIs. Please ask on the nbdev@netbeans.org mailing list if you have any questions about the details of a change, or are wondering how to convert existing code to be compatible.


Index of APIs

Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

All changes by date

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.netbeans.api.debugger.jpda/1 > 1.20

Changes by affected class

org.netbeans.spi.debugger.jpda.BreakpointsClassFilter

org.netbeans.api.debugger.jpda.CallStackFrame

org.netbeans.api.debugger.jpda.ClassVariable

org.netbeans.api.debugger.jpda.DeadlockDetector

org.netbeans.spi.debugger.jpda.EditorContext

org.netbeans.spi.debugger.jpda.Evaluator

org.netbeans.api.debugger.jpda.ExceptionBreakpoint

org.netbeans.api.debugger.jpda.FieldBreakpoint

org.netbeans.api.debugger.jpda.InvalidExpressionException

org.netbeans.api.debugger.jpda.JPDAArrayType

org.netbeans.api.debugger.jpda.JPDABreakpoint

org.netbeans.api.debugger.jpda.JPDAClassType

org.netbeans.api.debugger.jpda.JPDADebugger

org.netbeans.api.debugger.jpda.JPDAStep

org.netbeans.api.debugger.jpda.JPDAThread

org.netbeans.api.debugger.jpda.LineBreakpoint

org.netbeans.api.debugger.jpda.MethodBreakpoint

org.netbeans.api.debugger.jpda.MonitorInfo

org.netbeans.api.debugger.jpda.MutableVariable

org.netbeans.api.debugger.jpda.ObjectVariable

org.netbeans.api.debugger.jpda.ReturnVariable

org.netbeans.spi.debugger.jpda.SmartSteppingCallback

org.netbeans.spi.debugger.jpda.SourcePathProvider

org.netbeans.api.debugger.jpda.ThreadsCollector

org.netbeans.api.debugger.jpda.Variable

org.netbeans.api.debugger.jpda.VariableType


Details of all changes by API and date


Debugger JPDA API

Randomly select listening port

Jun 15 '19; API spec. version: 3.12; made by: jtulach
Enhanced behavior of ListeningDICookie.create(-1) method.

Differentiate application-level exceptions

Oct 26 '16; API spec. version: 3.7; affected top-level classes: InvalidExpressionException; made by: mentlicher; issues: #268011
InvalidExpressionException can be thrown as a result of an application-level exception. We need to differentiate this case from exceptions thrown from NetBeans code. A boolean argument in the constructor and a method hasApplicationTarget() are added to InvalidExpressionException for this purpose.

Enhanced smart-stepping.

Oct 21 '15; API spec. version: 3.5; affected top-level classes: SmartSteppingCallback; made by: mentlicher; issues: #255918
SmartSteppingCallback.stopAt() method added to be able to override the default smart-stepping logic and provide specific steps that should be performed at given locations.

Add methods for retrieval of implemented and extended types.

Jul 10 '15; API spec. version: 3.2; affected top-level classes: JPDAClassType ClassVariable; made by: mentlicher; issues: #253295
Methods that provide implemented and extended types were added to JPDAClassType class. These are: Associated with this is also an ability to retrieve the reflected type from the class variable. Therefore, we add following method to ClassVariable:

Add information about native methods into EditorContext.Operation.

Sep 8 '14; API spec. version: 2.51; affected top-level classes: EditorContext; made by: mentlicher; issues: #246819
A new method createMethodOperation(), which takes boolean isNative is added to EditorContext class. The EditorContext.Operation has isNative() method to retrieve that information. The implementation retrieves the native flag from parser information, therefore there can occur native methods at runtime, which are not marked as native by this flag.

Add a way to create mirror objects in the target VM and execute static methods.

Oct 24 '13; API spec. version: 2.47; affected top-level classes: JPDADebugger JPDAClassType; made by: mentlicher; issues: #237233
createMirrorVar() methods are introduced in JPDADebugger class. They create a mirror object in the target virtual machine.

Similar to invokeMethod() method on ObjectVariable, invokeMethod() is introduced on JPDAClassType for invocation of static methods.

A possibility to get/set mirror objects from debugger variables.

Apr 30 '13; API spec. version: 2.44; affected top-level classes: Variable MutableVariable; made by: mentlicher; issues: #228894
MutableVariable interface is introduced. It's to be implemented by variables that can change their values. Field, LocalVariable and JPDAWatch now extend MutableVariable.

Object createMirrorObject() method is added to Variable class and void setFromMirrorObject(Object obj) method is declared by MutableVariable.

Breakpoints can deactivated.

Feb 27 '13; API spec. version: 2.42; affected top-level classes: JPDADebugger; made by: mentlicher; issues: #79027
Two methods are added to JPDADebugger class: getBreakpointsActive() and setBreakpointsActive(boolean). The set method fires PROP_BREAKPOINTS_ACTIVE event.
These methods are used to activate/deactivate all breakpoints in the debugger session. Initially, the breakpoints are active in the debugger session.

Breakpoints can be made session-specific.

Feb 19 '13; API spec. version: 2.41; affected top-level classes: JPDABreakpoint; made by: mentlicher; issues: #226029
getSession()/setSession() methods are added to JPDABreakpoint class. They can be used to make the breakpoint debugger session-specific.

BreakpointsClassFilter provider introduced.

Aug 4 '12; API spec. version: 2.37; affected top-level classes: BreakpointsClassFilter; made by: mentlicher; issues: #215680
BreakpointsClassFilter introduced to provide a customized set of classes for breakpoints.

JPDADebugger.startListeningAndGetEngines().

Mar 23 '10; API spec. version: 2.26; affected top-level classes: JPDADebugger; made by: mentlicher; issues: #182439
JPDADebugger.startListeningAndGetEngines() introduced to return the debugger engines that are started, for use by the fix of the defect #182439. This method is identical to JPDADebugger.startListening(), but returns the started engines.

Property for classes fixed event added.

Feb 14 '10; API spec. version: 2.25; affected top-level classes: JPDADebugger; made by: dprusa; issues: #180695
JPDA debugger properties have been extended by a property name for classes fixed event. This event is usually generated when the user invokes Apply Code Changes action.

Added field:
JPDADebugger.PROP_CLASSES_FIXED

API for ability to plug-in evaluator engine.

Sep 10 '09; API spec. version: 2.21; affected top-level classes: Evaluator; made by: mentlicher; issues: #171342

An Evaluator interface is introduced, with evaluate() method. It's implementation should be registered for the desired language that compiles into bytecode.

Annotations for debugger service registration.

Feb 2 '09; API spec. version: 2.19; made by: mentlicher; issues: #153093 #156687

Annotations are added for easy registration on module layers. *Provider.Registration annotations are introduced to register implementations of appropriate providers.

Improve threading model.

Jan 13 '09; API spec. version: 2.18; affected top-level classes: JPDAThread; made by: mentlicher; issues: #156368
ReadWriteLock is introduced to synchronize the access to JPDAThread. ReadLock of that read/write pair is publicly available through the new method JPDAThread.getReadAccessLock(). Clients can use this lock to assure that the thread is not resumed in the mean time.

Added methods:
JPDAThread.getReadAccessLock(),

Enhance JPDA API with better thread control.

Jun 2 '08; API spec. version: 2.16; affected top-level classes: CallStackFrame DeadlockDetector JPDADebugger JPDAThread MonitorInfo ThreadsCollector EditorContext; made by: mentlicher; issues: #136099
This API change is necessary for the redesign of the debugger UI and it's behavior with respect to threads.

Added classes:
org.netbeans.api.debugger.jpda.DeadlockDetector, org.netbeans.api.debugger.jpda.MonitorInfo, org.netbeans.api.debugger.jpda.ThreadsCollector

Added methods:
CallStackFrame.getFrameDepth(), CallStackFrame.getOwnedMonitors(), JPDADebugger.getThreadsCollector(), JPDADebugger.getDeadlockDetector(), JPDAThread.getCurrentBreakpoint(), JPDAThread.getContendedMonitorAndOwner(), JPDAThread.getOwnedMonitorsAndFrames(), EditorContext.annotate() with thread argument, AttachingDICookie.getProcessID()

Added fields:
JPDADebugger.PROP_THREAD_STARTED, JPDADebugger.PROP_THREAD_DIED, JPDADebugger.PROP_THREAD_GROUP_ADDED, JPDAThread.PROP_SUSPENDED, JPDAThread.PROP_BREAKPOINT, EditorContext.OTHER_THREAD_ANNOTATION_TYPE

API for identification of method declarations in source code.

May 21 '07; API spec. version: 2.12; affected top-level classes: EditorContext; made by: mentlicher; issues: #103934

In order to implement annotation of method breakpoints in Editor, we need to be able to locate individual methods in Editor, based on their names and signature. Also we need annotation types for fields and methods.

Added methods:
EditorContext.getMethodLineNumber(), EditorContext.getCurrentMethodDeclaration(),

Added fields:
EditorContext.FIELD_BREAKPOINT_ANNOTATION_TYPE, EditorContext.DISABLED_FIELD_BREAKPOINT_ANNOTATION_TYPE, EditorContext.METHOD_BREAKPOINT_ANNOTATION_TYPE EditorContext.DISABLED_METHOD_BREAKPOINT_ANNOTATION_TYPE

Enhance JPDA breakpoints.

May 21 '07; API spec. version: 2.13; affected top-level classes: ExceptionBreakpoint FieldBreakpoint JPDABreakpoint LineBreakpoint MethodBreakpoint; made by: mentlicher; issues: #103936

To catch-up with JDI capabilities and be able to implement new enhancements, we need to add support for new breakpoint properties into the debugger JPDA API.
These are mainly class and thread filters and hit counts.

Added methods:
ExceptionBreakpoint.getClassFilters(), ExceptionBreakpoint.setClassFilters(), ExceptionBreakpoint.getClassExclusionFilters(), ExceptionBreakpoint.setClassExclusionFilters(), FieldBreakpoint.getInstanceFilters(), FieldBreakpoint.setInstanceFilters(), FieldBreakpoint.getThreadFilters(), FieldBreakpoint.setThreadFilters(), JPDABreakpoint.getHitCountFilter(), JPDABreakpoint.getHitCountFilteringStyle(), JPDABreakpoint.setHitCountFilter(), LineBreakpoint.getInstanceFilters(), LineBreakpoint.setInstanceFilters(), LineBreakpoint.getThreadFilters(), LineBreakpoint.setThreadFilters(), MethodBreakpoint.getMethodSignature(), MethodBreakpoint.setMethodSignature(), MethodBreakpoint.getInstanceFilters(), MethodBreakpoint.setInstanceFilters(), MethodBreakpoint.getThreadFilters(), MethodBreakpoint.setThreadFilters().

Added fields:
ExceptionBreakpoint.PROP_CLASS_FILTERS, ExceptionBreakpoint.PROP_CLASS_EXCLUSION_FILTERS, FieldBreakpoint.PROP_INSTANCE_FILTERS, FieldBreakpoint.PROP_THREAD_FILTERS, JPDABreakpoint.PROP_HIT_COUNT_FILTER, JPDABreakpoint.HIT_COUNT_FILTERING_STYLE, LineBreakpoint.PROP_INSTANCE_FILTERS, LineBreakpoint.PROP_THREAD_FILTERS, MethodBreakpoint.PROP_METHOD_SIGNATURE, MethodBreakpoint.PROP_INSTANCE_FILTERS, MethodBreakpoint.PROP_THREAD_FILTERS.

Support for heap walking.

Apr 5 '07; API spec. version: 2.11; affected top-level classes: JPDADebugger JPDAClassType ObjectVariable VariableType JPDAArrayType; made by: mentlicher; issues: #100047

In order to be able to provide heap walking functionality, we need methods for retrieval of class instances and back references.

Added methods:
Field.getDeclaringClass(), JPDAClassType.getClassLoader(), JPDAClassType.getSuperClass(), JPDAClassType.getInstanceCount(), JPDAClassType.getInstances(), JPDADebugger.canGetInstanceInfo(), JPDADebugger.getAllClasses(), JPDADebugger.getClassesByName(), JPDADebugger.getInstanceCounts(), ObjectVariable.getReferringObjects(), ObjectVariable.getClassType(), ObjectVariable.getUniqueID().

Added classes:
VariableType, JPDAArrayType.

API for retrieval of method arguments.

Mar 28 '07; API spec. version: 2.10; affected top-level classes: EditorContext; made by: mentlicher; issues: #99257

An access to method arguments in source code is necessary for cases where we do not have full debug information.

Added methods:
EditorContext.getArguments()

Added classes:
EditorContext.MethodArgument

Support for stepping over operations.

Feb 1 '07; API spec. version: 2.9; affected top-level classes: JPDAStep CallStackFrame JPDAThread EditorContext; made by: mentlicher; issues: #93842

In order to be able to provide stepping over operations, we need a representation of an operation and some way how to retrieve the operation(s) from a Thread and a CallStackFrame.

Added fields:
JPDAStep.STEP_OPERATION, EditorContext.CURRENT_LAST_OPERATION_ANNOTATION_TYPE, EditorContext.CURRENT_EXPRESSION_SECONDARY_LINE_ANNOTATION_TYPE, EditorContext.CURRENT_EXPRESSION_CURRENT_LINE_ANNOTATION_TYPE

Added methods:
CallStackFrame.getCurrentOperation(), JPDAThread.getCurrentOperation(), JPDAThread.getLastOperations(), EditorContext.createMethodOperation(), EditorContext.addNextOperationTo(), EditorContext.createPosition(), EditorContext.getOperations()

Added classes:
EditorContext.BytecodeProvider, EditorContext.Operation, EditorContext.Position

Added setPreferedClassName and getPreferredClassName methods to LineBreakpoint

Aug 30 '06; API spec. version: 2.8; affected top-level classes: LineBreakpoint; made by: mentlicher; issues: #83188

In order to be able to provide the class name for which the breakpoint should be submitted. This is necessary for JSP.

Added JPDAClassType, ClassVariable and ReturnVariable classes

Jul 12 '06; API spec. version: 2.7; affected top-level classes: JPDAClassType ClassVariable ReturnVariable; made by: mentlicher; issues: #80090

In order to be able to provide static context information and return value of methods, three new classes were added.

Added getSourceRoot() method to SourcePathProvider class

May 3 '06; API spec. version: 2.6; affected top-level classes: SourcePathProvider; made by: mentlicher; issues: #52180

Retrieves a source root for a given URL. This is necessary to match breakpoint locations with the sources selected fopr debugging. It returns null by default.

Added canBeModified() method to JPDADebugger class

Nov 3 '05; API spec. version: 2.3; affected top-level classes: JPDADebugger; made by: mentlicher; issues: #67046

A possibility to detect whether the debuggee is read-only is added. This check works fine on JDK 1.5 and higher, on JDK 1.4 it returns true by default.

Added interrupt method to JPDAThread class

Aug 18 '05; API spec. version: 2.1; affected top-level classes: JPDAThread; made by: mentlicher; issues: #59072

A possibility to interrupt a debuggee thread is added.

JPDA API interfaces that correspond to JDI API declared as not to implement.

Aug 12 '05; API spec. version: 2.0; made by: mentlicher

JPDA API represents JDI functionality. Since JDI interfaces evolve from one version to another, it's necessary to declare that interfaces in org.netbeans.api.debugger.jpda package should not be implemented, since new methods can be added to these interfaces at any time to keep up with the JDI functionality.

Also JPDABreakpointEvent and JPDABreakpointListener are moved to newly created org.netbeans.api.debugger.jpda.event package.

JPDAStep class added (also new method createJPDAStep added to JPDADebugger)

Jun 29 '05; API spec. version: 1.5; made by: rondruska

JPDAStep allows to create a step request to JDI with no UI interference. It was designed for new RunIntoMethod action. New method JPDADebugger.createJPDAStep creates a new instance of JPDAStep.


Binary-compatible

LineBreakpoint supplied with the information about the source path where it is set.

Feb 15 '05; API spec. version: 1.3; affected top-level classes: LineBreakpoint; made by: lkotouc

A line breakpoint does not contain the information about the source path where it is set. There is no way how to differ between breakpoints in the case when - several JSPs have the same name AND - these JSPs are statically included into one JSP page.

"global" parameter added to "SourcePathProvider.getURL (String relativePath, boolean global)" method.

Oct 18 '04; made by: jjancura

This parameter has been added to distinguish between finding sources for smart stepping feature, and for all other features like douuble click on stack trace..

"EditorContext.updateTimeStamp(timeStamp,url)" method has been added.

Oct 13 '04; made by: jjancura

This method is needed to correctly implement fix & continue action.

"String EditorContext.getClassName (url, lineNumber)" method has been added.

Oct 8 '04; made by: jjancura

This method is needed to correctly implement line breakpoint in secondary classes.

Two methods added to ContextProvider.

Jun 8 '04; made by: jjancura

ContextProvider.getImports () method added to support better evaluation of expressions. ContextProvider.getLineNumber (annotaion) method added to fix stepping through modified files.

ContextProvider and EngineContextProvider has been changed from interfaces to abstract classes.

Jun 8 '04; made by: jjancura

ContextProvider and EngineContextProvider has been changed from interfaces to abstract classes. This was done to support future changes in these classes.

InvalidExpressionException can encapsulate other exceptions.

Jun 1 '04; made by: jjancura

Mew constructor added (InvalidExpressionException(java.lang.Throwable)), and InvalidExpressionException.getTargetException() method added to support firing of nested exceptions.

ContextProvider.getFieldLineNumber() method added.

Jun 1 '04; made by: jjancura

ContextProvider.getFieldLineNumber() method added.

Firing of exceptions during watches evaluation fixed.

May 25 '04; made by: jjancura

InvalidExpressionException is fired from folowing methods now:

JPDADebugger.SESSION_ID.

May 17 '04; made by: jjancura

JPDADebugger.SESSION_ID constant has been added.

Improvements of SmartStepping implementation.

May 16 '04; made by: jjancura

We have added several new methods to fix issues in smart stepping implementation:

JPDABreakpointEvent improvements.

May 11 '04; made by: jjancura

We have added several new properties to JPDABreakpointEvent:

Definition of various breakpoints has been generalized.

May 10 '04; made by: jjancura

We have changed ClassLoadUnloadBreakpoint to support class exclusion filters, and more than one class filter. The same change was done for MethodBreakpoints too.

Support methods for various new features added.

May 9 '04; made by: jjancura

Support for Fix Action improved. Support for Pop Frame action added. Support for static and inherited fields added. New methods:

Breakpoint Listener added.

May 4 '04; made by: jjancura

JPDABreakpointEvent and JPDABreakpointListener classes added. JPDABreakpoint.addJPDABreakpointListener (...) and JPDABreakpoint.removeJPDABreakpointListener (...) methods added.

Support for synchronouous start of JPDADebugger added.

May 3 '04; made by: jjancura

Methods starting debugger has been modified to support synchronous start of debugging.

JPDADebugger.getException() method added.

Apr 20 '04; made by: jjancura
JPDADebugger.getException() method added to. This is support for notifications about problems during start of debugger.