JPDA Debugger API
Official

The JPDA Debugger API module defines common API for Java debuggers.

See:
Description

JPDA Debugger API

org.netbeans.api.debugger.jpda	JPDA Debugger APIs provide representation of JDI functionality.
org.netbeans.api.debugger.jpda.event
org.netbeans.spi.debugger.jpda	JPDA Debugger SPIs defines support for Smart Stepping, Variables Filtering and filtering of all Debugger Views.

The JPDA Debugger API module defines common API for Java debuggers.
List of APIs:

• JPDADebuggerAPI JPDA Debugger API
• JPDADebuggerSPI JPDA Debugger SPI
• Meta-inf-debugger-netbeans-JPDASession-Java-org.netbeans.spi.debugger.jpda.JPDADebugger Debugger View loads all model definitions.
• Meta-inf-debugger-netbeans-JPDASession-org.netbeans.spi.debugger.jpda.JPDADebugger Debugger View loads all model definitions.

What is New (see all changes)?

• Jun 2 '08 Enhance JPDA API with better thread control.

  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

• May 21 '07 API for identification of method declarations in source code.

  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

• May 21 '07 Enhance JPDA breakpoints.

  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.

• Apr 5 '07 Support for heap walking.

  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.

• Mar 28 '07 API for retrieval of method arguments.

  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

Use Cases

UseCase I. - Install and use CPP debugger plug-in to NetBeans + Java Debugger.

CPP debugger plug-in installs support for debugging of some new language to the NetBeans IDE, and some new debugging engine. This implementation of debugger should share UI components (actions, Debugger Views, ...) with default NB Java Debugger. It should share basic debugger model too - notion of current context, current session, thread, call stack line, ...

CPP debugger plug-in installs:

• New set of breakpoint types - CPPLineBreakpointType, CPPMethodBreakpointType...
  • This set of breakpoint types will have special cathegory in Add Breakpoint Dialog called "CPP". Each breakpoint type will install a new JPanel to Add Breakpoint Dialog.
  • ToggleBreakpointAction on CPP files will create / remove a instance of CPPLineBreakpointType.
• Install some watches evaluator for CPP language.
• Some new View to Debugger Window
• Use Termilnal Emulator in Output Window as command line interface to CPP debugger plug-in.
• Install / uninstall a columns to / from standard Debugger Window Views.
• Redefine Nodes used for representation of CPP threads, watches, variables, callstacks, sessions and breakpoints
  • Add / remove some properties
    
  • Add / remove some actions
  • change icons
  • change display names
• Register CPP Actions for:
  • Step Into, Over, Out, Continue, Pause, Start, Kill, Restart, Finish
• Some new CPP specific actions.

UseCase II. - Install and use JSP debugger plug-in to NetBeans + Java Debugger.

JSP debugger plug-in installs support for debugging of some new language to the NetBeans Java Debugger. It does not contain a new debugger engine, but it delegates to standard NB Java debugger. So it does not depends on Debugger Core API only, but it depends on JavaDebugger API too.

JSP debugger plug-in installs:

• New set of breakpoint types - JSPLineBreakpointType, ...
  • This set of breakpoint types will have special cathegory in Add Breakpoint Dialog called "JSP". Each breakpoint type will install a new JPanel to Add Breakpoint Dialog.
  • ToggleBreakpointAction on JSP files will create / remove a instance of JSPLineBreakpointType.
  • JSPLineBreakpointType delegates all functionality to JPDAClassBreakpoint and JPDALineBreakpoint
    
• Some watches evaluator for JSP language expression. This evaluator delegates evaluation of Java expressions to standard JavaExpressionEvaluator.
  
• Redefine Nodes used for representation of JSP callstacks and breakpoints
  • Add / remove some properties
    
  • Add / remove some actions
  • change icons
  • change display names
• Register JSP Actions for:
  • Step Into, Over, Out
  • Implementation of this actions delegates to standard Java Step actions - it redefines Java stepping functionality.
• JSP debugger plug in adds support for new programming language (JSP) to already running Java Session.
  

UseCase III. - Install and use J2EE debugger plug-in to NetBeans + Java Debugger.

J2EE debugger plug-in installs some enhancements to the standard Java Debugger. It does not contain a new debugger engine or language support. So it does not depends on Debugger Core API only, but it depends on JavaDebugger API too.

J2EE debugger plug-in installs:

• New set of breakpoint types
• Filter for Threads and Callstack Views. This filter should allow to:
  
  • Add / remove / modify nodes in this views.
• Redefine Stepping (Smart Stepping) behaviour of default Java Debugger.
• Some new View to Debugger Window

UseCase IV. - Install and use DBX debugger plug-in to NetBeans.

DBX debugger plug-in installs support for debugging of some new language (CPP) to the NetBeans IDE, and some new debugging engine. But it contains debugger engine for Java debugging too. DBX debugger engine has its own session management (or will have in the next versions). One debugger engine can manage more than one sessions. One engine supports debugging in more than one language.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...

Group of java interfaces

Interface Name	In/Out	Stability	Specified in What Document?
JPDADebuggerAPI	Exported	Official	../org-netbeans-api-debugger-jpda

Group of lookup interfaces

Interface Name

In/Out

Stability

Specified in What Document?

Group of property interfaces

Interface Name	In/Out	Stability	Specified in What Document?
SS_ACTION_STEPOUT	Exported	Friend	When set to Boolean.TRUE, this option is causing step out during smart-stepping instead of step into. Thus it much faster skips code that is not selected for debugging, but it may also skip code that should be debugged if it's called from a source that has debugging disabled. This is advantageous when the speed is important (e.g. in J2ME). This property can be set through a map of properties that is passed to JPDADebugger.attach (), like J2ME_DEBUGGER property.
netbeans.debugger.show_hidden_breakpoints	Exported	Private	This system property is causing the breakpoints view to show also hidden breakpoints.
org.netbeans.modules.debugger.jpda.breakpoints.level	Exported	Private	Logging level for informational messages about breakpoint submission and hits. They use Level.FINE and Level.FINER levels and are printed into the NetBeans message log.
netbeans.debugger.start	Exported	Private	When this system property is set, informational messages about start of JPDA debugger are printed into standard output (console).
netbeans.debugger.jditrace	Exported	Private	This system property sets the debug mode of the debuggee virtual machine via VirtualMachine.setDebugTraceMode() method. See the javadoc of that method for the description and possible values.
org.netbeans.modules.debugger.jpda.jdievents.level	Exported	Private	Logging level for informational messages about received JDI events. They use Level.FINE level and are printed into the NetBeans message log.
netbeans.debugger.smartstepping	Exported	Private	When this system property is set, informational messages about the smart stepping process are printed into standard output (console).
netbeans.debugger.noInvokeMethods	Exported	Private	When this system property is set, methods invocation in debuggee is disabled.
org.netbeans.modules.debugger.jpda.invokeMethod.level	Exported	Private	Logging level for messages about method invocation. They use Level.FINE level and are printed into the NetBeans message log.
org.netbeans.modules.debugger.jpda.getValue.level	Exported	Private	Logging level for messages about variables evaluation. They use Level.FINE level and are printed into the NetBeans message log.
netbeans.debugger.viewrefresh	Exported	Private	When this system property is set, informational messages about the tasks that refresh debugger views are printed into standard output (console). The value of that property should contain 'w' for watches view, 'l' for local variables view, 'c' for call stack view, 's' for classes view and 't' for threads view.

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Nothing.

Read more about the implementation in the answers to architecture questions.